Scripting PyBritive

Overview

PyBritive is designed to be driven by other programs. Three flags turn it from an interactive tool into a predictable JSON source, and the api command exposes the whole Britive Python SDK when the built-in commands are not enough.

What you’ll learn:

Which flags make output machine-readable
Where --format applies and where --mode applies instead
How to call SDK methods with pybritive api
How to invoke PyBritive safely from Ruby, Python, and bash

Before You Begin

PyBritive installed and able to authenticate — interactively, with BRITIVE_API_TOKEN, or with a federation provider
jq for the shell examples

The Three Flags

Silence prompts and progress

pybritive ls secrets --silent

--silent (-s) suppresses interactive prompts and progress output. Without it, a command waiting for approval prints status lines into your JSON.

Ask for JSON

pybritive ls secrets --silent --format json

Every command that lists or shows something takes --format (-f): ls, secret view, secret download, api. Values include json, yaml, csv, and many table-* styles.

Use `--mode json` for checkout

checkout does not take --format. Its output shape is chosen by --mode (-m), because a checkout can do things — write a credentials file, print exports — as well as print:

pybritive checkout "AWS Production/123456789012 (prod)/ReadOnly" --silent --mode json

{
  "accessKeyId": "ASIA…",
  "secretAccessKey": "…",
  "sessionToken": "…",
  "expiration": "2026-09-24T12:00:00Z"
}

checkin prints nothing.

Options are per-subcommand and go after it: pybritive ls secrets --format json, not pybritive --format json ls secrets.

The `api` Command

Everything the Britive Python SDK can do is reachable as pybritive api <module.method> --param value. Parameters use kebab-case.

pybritive api application_management.applications.list --format json \
  --query "[].{id: appContainerId, name: catalogAppDisplayName}"

pybritive api application_management.profiles.list \
  --application-id abc123 \
  --environment-association 123456789012 \
  --format json

--query takes a JMESPath expression, applied before output.

api is the administrative surface. Regular end-user identities will get 403 on most methods. Grant only the platform permissions the automation needs.

Calling PyBritive Safely

Pass arguments, not command strings

Secret paths contain spaces (/Team Secrets/db). Building a shell string breaks on them and invites injection. Pass an argument array:

Ruby

require 'open3'
out, err, status = Open3.capture3('pybritive', 'secret', 'view', path, '--silent', '--format', 'json')

Python

subprocess.run(["pybritive", "secret", "view", path, "--silent", "--format", "json"],
               capture_output=True, text=True, check=True)

bash

pybritive secret view "$path" --silent --format json

Keep the token out of argv

If you must use a token, set BRITIVE_API_TOKEN in the environment. Never pass --token: argv is visible in ps and process listings.

Set a timeout

An approval-gated profile makes checkout poll for up to ten minutes by default. Bound it with --maxpolltime and a process timeout in the caller.

Parse, then validate

secret view returns an object for templated secrets and a plain string for Note-type secrets. Check the type before indexing.

Putting It Together

List every secret you can read and print its keys — never the values:

pybritive ls secrets --silent --format json \
| jq -r '.[] | select(.path) | .path' \
| while IFS= read -r path; do
    printf '%s: ' "$path"
    pybritive secret view "$path" --silent --format json | jq -c 'if type=="object" then keys else type end'
  done

Expected output:

/Team Secrets/database: ["password","username"]
/Team Secrets/api-key: ["key","value"]
/Team Secrets/note: "string"

A small Ruby library that packages these patterns — argument arrays, timeouts, typed errors, and a Puppet adapter — will be linked here once published. See the Puppet integration for how it is used.

Troubleshoot

Symptom	Cause	Fix
JSON parse fails on the first line	Progress or prompt text mixed in	Add `--silent`
`no such option: --format` on `checkout`	`checkout` uses `--mode`	Use `--mode json`
Output is a table, not JSON	`--format` omitted and config default is `table`	Always pass `--format json` explicitly
`403` from an `api` call	Identity lacks platform permission	Grant the required role, or use `ls`/`secret`/`checkout` which only need profile and vault policies
Command hangs	Approval pending	Pass `--justification`, lower `--maxpolltime`, and set a caller-side timeout

Next Steps

Authenticate from AWS with Workload Federation — remove the token entirely
Working with Secrets — the secret command in depth
Approval Workflows — what happens when a checkout needs approval

Last updated on September 24, 2026

Authenticate from AWS with Workload Federation SSH Access