CLI reference
Every sourceorrery command and option: setup, vault, secret, audit, init, import, check, run, ui and completions, plus global options, opening a vault, the view check and exit codes.
sourceorrery [--vault NAME] [--home DIR] [-o table|json] [--recovery-key-file FILE] [--password-file FILE] [--code CODE] [-v] <command>| Global option | Env | Meaning |
|---|---|---|
--vault NAME |
SOURCEORRERY_VAULT |
Vault to use. Default: [project].vault from the nearest sourceorrery.toml. |
--home DIR |
SOURCEORRERY_HOME |
Directory holding vault files. |
-o, --output table|json |
Output format. Errors in JSON mode are {"error":{"code","message"}} on stderr. In table mode, control and bidi formatting characters in stored text (labels, audit actors and details) are shown as \u{..} escapes. |
|
--recovery-key-file FILE |
SOURCEORRERY_RECOVERY_KEY_FILE |
The vault’s recovery key, read from a file, where this machine cannot open the vault by itself (WSL, a container, CI, another machine). |
SOURCEORRERY_RECOVERY_KEY |
The recovery key from the environment. CI only; environment variables are visible to process inspection. | |
--password-file FILE |
SOURCEORRERY_PASSWORD_FILE |
The view check’s password, read from a file (scripts); with vault create and vault import, the password the vault’s check is set to. |
SOURCEORRERY_PASSWORD |
The view check’s password from the environment. | |
--code CODE |
SOURCEORRERY_TOTP |
A six-digit code from the authenticator app, for a vault whose view check asks for one. Without it the code is asked for on the terminal; a code is never read from a pipe. |
-v |
SOURCEORRERY_LOG |
Diagnostics on stderr. Never prints values. |
SOURCEORRERY_KEYRING=off |
Use no OS credential store: every vault opens with its recovery key. | |
SOURCEORRERY_AWS_INSTANCE_ROLE=on |
Let an AWS Secrets Manager connection with no stored access key use the EC2 instance role. Off by default: the instance-metadata address is plain HTTP, and off an instance whatever answers it could choose the account (AWS Secrets Manager). |
Exit status: 0 success, 1 any error (code in JSON mode), 2 usage error.
run exits with the child’s status, whole: a Windows status above 255
(such as 3010) is passed through unchanged, and a Unix child killed by a
signal exits 128 + signal, as a shell would.
Running sourceorrery with no arguments prints the text logo, a link to
sourceorrery.ai and a quick start. On a terminal the logo is drawn with
Unicode half blocks in colours chosen to read on dark and light
backgrounds; when piped it is plain text. SOURCEORRERY_BANNER=unicode|plain
forces a style.
Project setup options
Section titled “Project setup options”- Option 1: Set up with the CLI. Follow the CLI installation guide, then create the vault and set its secret values in your own terminal.
- Option 2: Set up with an AI coding agent. Run
sourceorrery init --integration all, then ask your agent to set up SourceOrrery for the project without showing values. You keep vault keys and new values private. The agent setup guide works with an existing CLI installation.
setup: a vault on screens
Section titled “setup: a vault on screens”sourceorrery setup [--guide] [--theme dark|light|terminal]sourceorrery vault create [NAME]setup and vault create [NAME] show the same screens on a terminal. With
no vault on this machine they create one; with vaults they list them, to
change one or create another. vault create NAME starts with the name
filled in, and the name of a vault that exists opens it for changes.
| Screen | What it does |
|---|---|
| Start | The vaults on this machine, Create a new vault, and whether this machine’s credential store keeps a vault’s key. |
| Name | The new vault’s name, checked as it is typed (letters, digits, hyphens, underscores, up to 64, unique ignoring case). |
| View check | Whether viewing the vault asks for a password, and an authenticator code on top of it (below). |
| Password | Typed twice with a strength meter (it must rate “good”), or generated and shown once behind a “written down” tick; an optional hint, refused if it gives the password away. |
| Authenticator | A complete QR code when it fits, with the manual enrolment key available on compact screens; the code field and controls remain reachable. A code from the app is checked before moving on; three wrong ones make a new key. |
| Recovery key | Shown once, behind a “written down” tick. When changing a vault it is kept unless a new one is asked for, and the old one then stops working in this file. A new recovery key is not a new vault key: an old copy of the vault still opens with the old key. After a compromise, rotate the exposed credentials and move to a new vault instead (threat model, gap 10). |
| Storage | The SourceOrrery vault (always) and HashiCorp Vault, AWS Secrets Manager and Azure Key Vault; a provider not built into this binary is shown as unavailable. |
| Connections | One form per provider ticked: its address, region or URL, and its credentials, either this machine’s sign-in (the provider’s own environment, CLI login or workload identity) or stored in the vault, sealed. Test connection makes one metadata call. |
| Review | Everything above. Create vault or Save changes makes it all in one transaction: nothing is written before it, and a part the vault refuses leaves everything as it was. |
| Done | The vault, its file, view check and storage, and what to run next: sourceorrery ui and sourceorrery init. |
Changing a vault never prompts: this machine’s key opens it, else its
recovery key is typed on the screen (which passes the view check by
itself), else its view check is asked there, with the hint. The review
commits only against the view check the screens passed, or found absent,
when they opened the vault: one set or changed elsewhere in the meantime
refuses the commit (permission_denied), and the vault is opened again.
Hidden fields are drawn as dots from their length; what is typed lives in
a buffer that is wiped, and goes to the vault at the review. The screens
are the Cargo feature ui.
setup --guide, or setup without a terminal or with -o json, prints
the one command that does the same without the screens:
sourceorrery vault create development --recovery-key-out development.recovery-key \ [--password-file FILE] \ [--hashicorp-vault ADDRESS [--hashicorp-vault-mount MOUNT] [--hashicorp-vault-token-file FILE]] \ [--aws-secrets-manager REGION [--aws-access-key-id ID --aws-secret-access-key-file FILE]] \ [--azure-key-vault URL [--azure-tenant-id ID --azure-client-id ID --azure-client-secret-file FILE]]The authenticator is set up on the screens only: it needs a code from the app.
Opening a vault
Section titled “Opening a vault”A vault’s key is kept twice: once for this machine, in its OS credential
store (Windows Credential Manager, macOS Keychain, Secret Service on
Linux), and once under the vault’s recovery key, shown when the vault
is made. The CLI tries this machine’s key first, without prompting. Where
that is not possible (WSL, a container, CI, another machine, an exported
copy, SOURCEORRERY_KEYRING=off) it takes the recovery key from
SOURCEORRERY_RECOVERY_KEY, else --recovery-key-file /
SOURCEORRERY_RECOVERY_KEY_FILE, else a hidden prompt when stdin is a
terminal, up to three attempts. A key from the environment or a file is
tried once; a wrong one is not retried. Failed attempts are audited.
run never passes any of these variables, or the password and code
variables below, to the program it starts.
The view check
Section titled “The view check”Opening a vault lets a process read its values. The view check is a second question for the moments a person views the vault or reveals a value: a password, and optionally a code from an authenticator app on top of it, set on the setup screens. It is a check, not encryption: the vault key does not depend on it.
It is asked by ui, secret list, secret get (with or without
--reveal), secret versions, audit and audit export, and before the
setup screens change a vault. run, check, init, import, the other
secret commands and every SDK never ask it, so an application keeps
starting without a prompt while an API key read out at the keyboard, by
you or by an agent, asks for more.
The password comes from SOURCEORRERY_PASSWORD, else --password-file,
else a hidden prompt (after the hint, if one is set). The code comes from
--code / SOURCEORRERY_TOTP, else a prompt on the terminal; it is never
read from a pipe, so a script that has neither is refused rather than
hung. A code is accepted once, for the current 30-second step or the one
either side of it. A vault opened with its recovery key has passed the
check: the recovery key opens it anywhere and is the stronger secret.
A refusal is permission_denied, audited under guard. After five wrong
answers in a row each further attempt waits, 30 seconds at first, doubling
to at most 15 minutes. The check is not a boundary against code running as
you with the vault key in reach; see the threat model.
sourceorrery secret get database-password --vault development --revealHint: the long onePassword of vault 'development':Code from the authenticator app: 123456| Command | Description |
|---|---|
vault create [NAME] |
On a terminal, without the flags below: the setup screens (--theme as for ui). |
vault create NAME [--recovery-key-out FILE] [--password-file FILE] [--no-keyring] [--retention-days 7-90] [--purgeable] [connection flags] |
Create the vault at once (scripts, CI, any of these flags, or no terminal). Its recovery key is printed once on stdout, or written to --recovery-key-out: a new file, created before the vault with permissions only you have (on Windows restricted to your account and Windows SYSTEM, read back and checked; on Unix mode 0600), and synced to disk; an existing file is never written over, and a volume that cannot keep permissions is refused. A key that cannot be delivered, to the file or to stdout, leaves no vault behind: the create is undone. --password-file sets the view check’s password (a weak one is warned about); --no-keyring keeps no key for this machine. The connection flags add one connection per provider, the credentials read from files only (below). The vault, its password and its connections are made in one transaction: a part refused creates nothing. -o json: vault, this_machine, keys (kind and id of each key that opens it), view_check, connections, and recovery_key or recovery_key_file. |
vault list |
The vault files in the home directory. It opens none of them. |
vault export [NAME] --out FILE |
A copy of the vault for another machine: a consistent snapshot of the file (settings, connections with their credentials still sealed, the catalog, the values it keeps, project folders and the audit log). This machine’s key and the view check stay behind, so the copy opens only with the recovery key; the copy’s own log records the export. --out must not exist. Not asked the view check: the copy is no more open than the file. |
vault import FILE [--name NAME] |
Bring an exported vault onto this machine: it is opened with its recovery key (the environment, --recovery-key-file or the prompt), its name, settings and audit chain are verified, this machine’s key is added and it is registered under its name or --name (a name that exists, ignoring case, is refused). It comes with no view check; --password-file sets one at once, and otherwise the output says how (vault create NAME on a terminal). |
vault destroy NAME [--yes] [--keep-os-key] |
Delete the vault file and the credential-store entries it provably owns (entries another vault file references are kept and reported). Irreversible. |
The connection flags of vault create:
| Provider | Flags |
|---|---|
| HashiCorp Vault | --hashicorp-vault ADDRESS (https://, or http:// to this machine), --hashicorp-vault-mount MOUNT (default secret), --hashicorp-vault-namespace NAMESPACE, --hashicorp-vault-token-file FILE (store the token in the vault instead of using VAULT_TOKEN and Vault’s other sign-in sources) |
| AWS Secrets Manager | --aws-secrets-manager REGION, --aws-secrets-manager-prefix PREFIX, --aws-secrets-manager-endpoint URL, --aws-access-key-id ID with --aws-secret-access-key-file FILE (store an access key) |
| Azure Key Vault | --azure-key-vault URL, --azure-tenant-id ID with --azure-client-id ID and --azure-client-secret-file FILE (store a service principal) |
Without stored credentials a connection signs in the way the provider’s own tools do on that machine. The providers, what each maps and what it cannot express are in providers.
secret
Section titled “secret”| Command | Description |
|---|---|
secret set NAME [--stdin | --from-file FILE] [--confirm] [--allow-empty] [--keep-trailing-newline] [--content-type T] [--tag K=V]... [--not-before T] [--expires T] [--disabled] [--storage STORAGE] [--description TEXT] |
Store a new version. Value source: --from-file, else stdin when piped (--stdin to force), else a hidden prompt. One trailing newline from stdin is stripped. There is no --value option. --storage says where a new secret is kept: sourceorrery (the vault file, the default), or a provider the vault has a connection to (hashicorp-vault, aws-secrets-manager, azure-key-vault, or the connection’s id); a new version of an existing secret goes where the secret is. --description is one line of what the secret is for (at most 200 characters), kept in the vault’s catalog and written into a manifest as purpose by init. Tag keys under sourceorrery. are SourceOrrery’s own (rotation state) and refused. |
secret get NAME [--version ID] [--reveal] [--raw] |
Metadata (default). --reveal prints the value + newline; --raw omits the newline. -o json --reveal adds value (or value_hex for non-UTF-8). Without --version, the newest accessible version is used. Asks the view check. |
secret list [--deleted] [--limit N] [--after NAME] |
Live secrets (newest version each), or soft-deleted ones, in name order, from wherever each is kept. Metadata only. --limit N shows one page of up to N and, while names follow, the --after NAME that continues it; -o json then prints {"items": [...], "continuation": "NAME"} instead of the plain array. Each page is one secret_list audit event. Asks the view check. |
secret versions NAME |
Every version, newest first, with status. Asks the view check. |
secret update NAME [--version ID] [--enable|--disable] [--content-type T|--clear-content-type] [--tag K=V...|--clear-tags] [--not-before T|--clear-not-before] [--expires T|--clear-expires] |
Change metadata of one version. Never the value. A provider that keeps these properties per secret, or cannot remove a time window, refuses what it cannot express (unsupported). |
secret delete NAME |
Soft-delete all versions (recoverable until retention ends). Immediate in a purgeable vault. |
secret recover NAME |
Undo a soft delete. |
secret purge NAME [--yes] |
Permanently remove a soft-deleted secret. |
secret rotate NAME [--manifest FILE] [--step rotate|activate|retire|status] [--no-activate] [--retire-after D] [--now] [--stdin | --from-file FILE] [--keep-trailing-newline] [--allow-empty] |
Rotate a credential: issue a new value (the manifest’s [rotation.NAME] issue command, else stdin, a file or a prompt), validate it with the validate command, activate it (enable the new version, then disable the previous one), and retire the previous one with the retire command once retire_after (or --retire-after) has passed, in a later --step retire run; without a grace period, in the same run. State lives in sourceorrery.rotation.* tags; refusals carry the code rotation. A secret kept at AWS Secrets Manager cannot be rotated (unsupported: its properties are per secret). See rotation. |
A secret kept at a provider is read and changed there through the vault’s connection, and the vault records each call in its own audit log.
Status column values: enabled, disabled, pending (before not_before),
expired.
Timestamps are RFC 3339, e.g. 2026-12-31T00:00:00Z.
sourceorrery audit [--secret NAME] [--operation OP] [--since TIME] [--limit N]sourceorrery audit --verifysourceorrery audit --acknowledge [--yes]sourceorrery audit export [--format jsonl|otlp] [--since TIME] [--follow] [--interval S] [--endpoint URL] [--header K=V]... [--batch N]Newest first, with each event’s id. audit and audit export ask the
view check. Operations:
| Operation | Recorded for |
|---|---|
vault_create, vault_open |
Creating the vault; each open (a failed one with outcome failure, detail locked). |
secret_set, secret_get, secret_list, secret_inspect, secret_update, secret_delete, secret_recover, secret_purge |
The secret operations; secret_inspect is a metadata read (properties, versions, a deleted secret’s details). A call to a provider is recorded the same way, by the vault, with the provider’s outcome. |
guard |
The view check: an answer passed or refused (denied), each change to it (password set or changed, check cleared, authenticator enrolled and verified or removed), and each change refused (failure, the error code only: never the password or hint it was given). |
protector_add |
The recovery key replaced, or this machine’s key added. Its event checkpoints the new set of key wraps. |
vault_change |
A connection added, changed or removed, and a change of settings refused as a whole (failure). |
connection_test |
A connection tested (success, or failure with the error code). |
vault_export, vault_import |
The vault exported (in the copy’s own log) or imported. |
project_link, project_unlink |
A project folder recorded by init, or forgotten in the ui. |
audit_verify |
A detected truncation (failure) and its acknowledgement (success). |
Older releases also recorded protector_remove, vault_migrate,
vault_backup and secret_restore; they are kept as names, never
recorded now. Outcomes: success, denied (policy), failure,
pending and unknown. A change at a connection is recorded as a
pending attempt before it is sent (at connection <id>: sent), and the
event with its result names it ((attempt <id>)); unknown is a change
the provider may have made (outcome_unknown). After the events, audit
names every attempt whose result the vault never learned and what to do
(providers).
Detail holds the error code or a short note — never a value, a code, a
password, a credential or the hint.
--verify checks the log’s keyed hash chain instead of listing it (see
vault-format.md) and prints:
| field | meaning |
|---|---|
rows |
audit rows examined |
keyed |
rows authenticated with the vault key |
unkeyed |
rows written before the vault was opened (failed attempts); chained with a public key, so forgeable but not silently removable |
first_broken |
id of the first row whose link or hash does not verify, else - / null |
truncations |
times a write found rows removed from the end of the log (each is an audit_verify / failure event); acknowledged ones still count |
unacknowledged |
truncations not yet acknowledged with --acknowledge; while this is not 0 the vault refuses every other command |
head_valid |
the recorded chain head names the newest keyed row |
result |
intact or BROKEN |
The result is always printed (as JSON with -o json); when the chain is not
intact the command also fails with exit status 1. Verification is read-only,
but opening the vault to run it writes the usual vault_open row.
audit export: the log for a collector
Section titled “audit export: the log for a collector”audit export writes the whole log, oldest first, for the place the
organisation already collects logs, and ends with the chain verification
so a collector can tell a complete export from a truncated log:
--format jsonl(default): one JSON object per line on stdout, the event asaudit -o jsonshows it plus"vault", then one trailer line{"vault", "events", "last_id", "intact", "verification": {…}}with the fields ofaudit --verify. Vector, Fluent Bit and their kind read it without help (sourceorrery audit export --vault production | vector --config …, or afilesource on a redirected file).--format otlp --endpoint URL: the same records as OTLP/HTTP log records (JSON encoding,POST …/v1/logs) in batches of--batch(500), for a collector that speaks OTLP directly. Each event is a log record whose body is<operation> <outcome> [<secret>], severityINFO,WARN(denied) orERROR(failure), with the fields as attributes (sourceorrery.vault,sourceorrery.event.id,sourceorrery.operation,sourceorrery.outcome,sourceorrery.actor,sourceorrery.secret,sourceorrery.version,sourceorrery.detail); the verification is the last record, bodyaudit chain verification: intact|broken, withsourceorrery.audit.*attributes. The endpoint defaults toOTEL_EXPORTER_OTLP_LOGS_ENDPOINT, elseOTEL_EXPORTER_OTLP_ENDPOINTwith/v1/logsappended; headers come from--header KEY=VALUEandOTEL_EXPORTER_OTLP_HEADERS. Anhttps://collector’s certificate is verified against the operating system’s certificate store. A collector that answers anything but 2xx fails the export, with the status in the error. Built with the Cargo featureotlp(on by default); without it the command says so and JSON Lines remains.--since TIMEstarts from that time;--followkeeps the vault open and, after the backlog and its trailer, exports each new event as it is recorded (looking every--intervalseconds, default 2) until stdout closes or the process is stopped. Reading the log is not itself audited, so following adds nothing to it.
Exported records are the metadata the log holds, never a value. A secret
kept at a provider also appears in that provider’s own trail; audit
says where to look for each provider the vault’s secrets are kept at
(providers).
A truncated log blocks the vault
Section titled “A truncated log blocks the vault”If rows were removed from the end of the log since the last write, the
first command that opens the vault fails with crypto (“audit log
integrity: rows removed after event N …”): the vault judges every row
against the newest checkpoint in the log, so a shortened log is not
consulted. That refusal records the truncation (audit_verify /
failure), and from then on every command that opens the vault, and
every operation, fails with crypto naming that event (“… the truncation
detected at event 42 (…) is unacknowledged; the vault is blocked until
…”). Each refusal is recorded too.
The one exception is audit itself, which opens a blocked vault for
inspection: audit lists the log (and warns on stderr that the vault is
blocked), audit --verify reports the chain, and audit --acknowledge
lifts the block. Such an open writes vault_open / success with detail
inspection (truncation unacknowledged), skips the retention purge, and
still refuses every secret operation. ui opens vaults the same way so
that its audit log view works on a blocked vault; it shows nothing else
there and cannot acknowledge.
Treat a truncation as evidence that the file was edited. Whatever the
missing events recorded — a change of settings, a deletion, a new version
— is gone, and an attacker who removed them may also have put back older
copies of the rows they covered, or of the vault’s settings (the view
check, the connections), which the surviving history can no longer tell
from the truth. Compare the log, the secrets and the settings with an
exported copy (vault export), then:
sourceorrery audit --acknowledge --vault developmentprints the truncation events, asks for confirmation (--yes answers it,
for automation; in a non-interactive session without --yes the command
aborts and the vault stays blocked) and appends one keyed audit_verify /
success event, truncation acknowledged (event 42), which also records
the vault’s settings as they are now. After that the vault accepts
commands again, with the surviving history and those settings as its record;
audit --verify keeps reporting the truncation (truncations stays 1,
unacknowledged becomes 0, the result stays BROKEN). The acknowledgement
covers every truncation detected before it and nothing after: a truncation
detected by another process between listing and acknowledging is refused
with invalid_argument, and a log found shortened again at that moment is
recorded and refused. With nothing to acknowledge the command says so and
exits 0.
Project manifest: init, import, check, run
Section titled “Project manifest: init, import, check, run”Without --manifest, the commands look for sourceorrery.toml in the
current directory and its parents, no further than the repository (the
first directory with a .git entry), the home directory, and, on Unix,
directories and files owned by the home directory’s owner: a manifest
decides which vault a name means, so one planted in /tmp or a shared
parent is never picked up. Windows has no ownership bound yet: a folder
made at the root of a drive (C:\work) lets every account write in it by
default, so keep a project in a repository or under your profile, or pass
--manifest (threat model, known gap 15). --manifest FILE uses the file
it names.
sourceorrery.toml is the committed, value-free replacement for .env:
[project]name = "my-application"vault = "development"
[secrets.database-password]required = truepurpose = "Database authentication" # documentation only
[secrets.payment-api-key]required = falseenv = "STRIPE_KEY" # default: PAYMENT_API_KEYversion = "0123456789abcdef0123456789abcdef" # pin a version (optional)Any other key — in particular value, a per-secret vault or a
[vaults.*] table — is a parse error, reported by key name and position
without repeating the offending text. Where a secret is kept is the
vault’s business: the vault file, or a provider through one of its
connections; the manifest names the vault and the secrets. env names
must be unique ignoring case (Windows environments are case-insensitive)
and may not start with SOURCEORRERY_.
How a secret is rotated is a [rotation.<name>] table naming the commands
secret rotate runs (each the program and its arguments, no shell) and the
grace period; it cannot hold a value either:
[rotation.database-password]issue = ["./scripts/db-rotate.sh", "issue"] # stdout is the new valuevalidate = ["./scripts/db-rotate.sh", "validate"] # exit 0 accepts the candidateretire = ["./scripts/db-rotate.sh", "retire"] # revokes the previous credentialretire_after = "7d"See rotation for what each command receives.
| Command | Description |
|---|---|
init [VAULT] [--project-name NAME] [--all | --secret NAME...] [--path FILE] [--theme T] |
Write the project’s sourceorrery.toml from the vault’s secrets, by name, or add to the one there, and record the folder in the vault (below). |
init --integration AGENT[,AGENT...] [--scope project|user] [--skills-dir DIR] |
Install the SourceOrrery skills for AI coding agents (below). |
import FILE [--dry-run] [--manifest-only] [--only KEY]... [--exclude KEY]... [--overwrite] [--storage STORAGE] [--manifest FILE | --no-manifest] |
Move a .env file into the vault and declare its keys (below). |
check [--manifest FILE] [--access] |
Verify every entry resolves to an accessible version. Reads metadata only; writes no secret_get audit rows. Fails if a required secret is missing. --access also reads each value and discards it, so the status says whether this identity may read the secret and not only inspect it (a provider can allow metadata and deny values); that is an audited read. |
run [--manifest FILE] -- COMMAND [ARGS...] |
Resolve every entry and start COMMAND with the values in its environment (plus SOURCEORRERY_PROJECT). Missing required secrets abort before the child starts. Every variable the manifest names is the vault’s to set: an optional secret that does not resolve (missing, disabled, outside its window, deleted) leaves its variable absent in the child, never a value of that name inherited from this environment (on Windows matched in any case). Other variables pass through. The child never inherits the recovery-key, password or code variables. --vault overrides the manifest’s vault. |
The parent resolves values in memory without printing them, then passes them to the child through its environment. Processes with permission to inspect the child can read that environment; the child and its dependencies can also log or copy values. See the threat model.
init: the manifest from the vault
Section titled “init: the manifest from the vault”init needs a vault on this machine and reads its catalog (names, where
each is kept, descriptions) without the view check: it never needs a
value. The vault is the one an existing manifest names (another one asked
for is refused; a missing one points at vault import and vault create), else VAULT or --vault, else the only vault on this machine.
On a terminal, with no secret picked by a flag, init shows its own
screens:
| Screen | What it does |
|---|---|
| Vault | Which vault, when there is more than one. |
| Project | The project’s name (default: the folder’s) and where the manifest goes. |
| Secrets | The vault’s secrets as a checkbox list with All, a filter (/), and each secret’s storage, environment variable and description. With a manifest already there, its secrets are ticked, and one the vault lacks is marked: Enter gives it a value. |
| New secrets | A loop: “Add a new secret to the vault for this project?” A new one has a name (checked as typed), its value twice in hidden fields, its storage when the vault has connections, a description and its variable; Store puts it in the vault at once. |
| Review | What the manifest will declare, each with a required tick, what is taken out, and what was stored on this run. Nothing is written before Write sourceorrery.toml; leaving earlier says which secrets stayed in the vault. |
| Done | The manifest, and next: sourceorrery run -- <your command>, sourceorrery check. |
Without a terminal, --all declares every secret the vault holds and
--secret NAME (repeatable) the ones named; there is no way to store a
value from here, so a script stores new secrets first (secret set NAME --stdin). Each pick is declared as [secrets.<name>] with required = true and purpose from its description. An existing manifest is edited
in place: new entries land after its other secrets and every other byte
(comments, env overrides, version pins, [rotation.*] tables) stays.
Writing records the folder in the vault (project_link), which the ui
lists under Projects.
import: moving a .env file into a vault
Section titled “import: moving a .env file into a vault”sourceorrery import .env --dry-run # preview key names and planned changessourceorrery import .env # store the values, declare the keyssourceorrery --vault test import .env.test --storage aws-secrets-managersourceorrery import .env.example --manifest-onlyEach KEY=value becomes a secret named after the key in lower case with
hyphens (DATABASE_URL → database-url), stored as a new version in the
vault (--vault, else the manifest’s vault, else development), where
--storage says (the vault file by default), and tagged
imported-from=<file name>. Each key is declared in the nearest
sourceorrery.toml (created if there is none) by appending
[secrets.<name>] entries, so the file’s comments and existing entries are
kept; an env line is added when the default name would not deliver the
original variable (apiKey → env = "apiKey").
Nothing the command prints contains a value: the table (or -o json)
lists each key, its secret name, what happened in the vault and in the
manifest, and a note. A “key” is file text, and on a line that is not
really an assignment (a connection string or the end of wrapped base64 on
a line of its own) the text before = can be part of a value, so a key
that is not shaped like a variable name, or whose value is only =
padding, is shown as (not shown), in the table, in JSON and in errors,
and skipped. A secret the vault already holds is left as it is
(--overwrite stores a new version), so the command can be run again.
Keys that cannot become manifest entries are reported and skipped: an
invalid environment variable name, a name starting with SOURCEORRERY_,
an empty value. A key assigned twice, two keys that would map to the same
secret, a syntax error (reported by line number only) or a manifest that
would become invalid stops the command before anything is stored.
--manifest-only declares the keys without opening a vault, for
.env.example files.
The syntax is what python-dotenv, dotenv for Node and godotenv share:
KEY=value with optional export, # comments, single quotes and
backticks literal, double quotes with \n, \r, \t, \" and \\
escapes, multi-line quoted values. Nothing is expanded: a value containing
${...} is stored as written and noted.
init --integration: skills for AI coding agents
Section titled “init --integration: skills for AI coding agents”sourceorrery init --integration claudesourceorrery init --integration cursor,codex --scope usersourceorrery init --integration allWrites two skills, sourceorrery and sourceorrery-migrate-env, in the
Agent Skills format to the directory the agent reads: claude (and a
subagent), gemini, copilot, antigravity, cline, codex, cursor,
hermes, kilocode, kimi, kiro, opencode, or all. The skills are
compiled into the binary; nothing is downloaded. --scope user installs
them for every project on this machine, and --skills-dir DIR anywhere
else; neither writes a manifest. In a project, the manifest is written
too when --all or --secret picks secrets. Running it again updates the
files SourceOrrery wrote and leaves alone a skill of the same name that it
did not. Paths per agent, the Claude Code plugin and what the skills do:
AI coding agents.
sourceorrery ui [--vault NAME] [--theme dark|light|terminal] [--lock-after MINUTES] [--read-only]An interactive browser for the vaults in the home directory, which can
also change their secrets’ metadata. It shows metadata only. Its
browsing interface has no operation returning a stored value, so screen
buffers and metadata snapshots do not contain secret values. The process
still holds the opened vault key and briefly handles a new value entered
at the hidden prompt. Stored text is escaped as in every other table (see
--output above), so metadata in the file cannot drive the terminal.
Times are UTC.
| View | Shows |
|---|---|
1 Overview |
The vault at a glance. The header says what the view check asks for and where the vault keeps secrets. Panels: secrets by status and by storage, by expiry, and what expires or activates next; the audit chain as audit --verify would report it (v checks it again); 14 days of activity, denials and failures marked, with the last value read and the last failed open; the vault (created, file, deletion, how it opens); the view check (password, hint, authenticator, when the recovery key was issued; c changes it); storage (each connection’s secrets, sign-in, last test and target, or that its provider could not be reached); projects (found and missing). |
2 Secrets |
Every live secret: status, storage, short version id, last update, expiry, the projects whose manifest declares it, tags. Enter opens its details: every field, where it is kept, the projects that use it, the sourceorrery:// reference, every version (newest first), and the secret’s recent audit events. |
3 Projects |
The project folders the vault records (by init): path, name, the number of secrets their manifest declares, and whether the folder’s sourceorrery.toml is there (✓) or gone (✗), as found when the vault was read. Enter shows the manifest’s secrets and whether each resolves in the vault, as check would say from metadata. |
4 Deleted |
Soft-deleted secrets, their purge date and the days left. Enter shows the fields and recent activity; a deleted secret’s versions cannot be listed until it is recovered. |
5 Audit log |
The newest 1000 events, denials and failures marked. |
6 Vaults |
The vault files in the home directory with size and modification time. Listing them needs no opening; Enter opens one, n creates one and c changes the selected one on the setup screens. |
Opening a vault. The vault named by --vault or the manifest is
opened, and its view check asked, before the screen is taken over,
with the usual order and prompts; if that fails, the command fails as any
other would. With no vault named, ui starts on Vaults. Opening a vault
from there suspends the screen for the same prompts (if any are needed)
and comes back to the browser. ui needs a terminal on stdin and stdout
and has no JSON output; both are checked before anything is opened, so a
refused start prompts for nothing and records nothing. Secrets a
connection stores are listed at its provider, one listing per connection;
a provider that cannot be reached is shown on the Overview, and the rest
of the vault is shown.
Locking. After --lock-after minutes without a key (default 10,
SOURCEORRERY_UI_LOCK_AFTER; 0 never locks), and at once on L, the
browser drops the open vault: its handle goes, and with it the vault key,
which is zeroised; everything read from it goes too. Enter opens it
again, asking what opening it asks, view check included.
The last 30 seconds show a countdown. Display ticks do not refresh metadata or extend the session. Synchronous provider work must return before input or locking can resume; the operation message makes that limit explicit.
Actions and complete details. F2 opens a contextual menu with the
same commands as the keyboard shortcuts. Unavailable actions explain why;
moving through the menu performs no write or provider read. i opens the
complete cached metadata, and ! opens a complete message. Both scroll
without fetching more data and return to the same underlying view.
Tables retain name/status first and hide lower-priority columns on narrow
screens. An ellipsis marks clipped metadata; use i or explicit details
for the full field. Counts distinguish matching rows from the visible row
range. Help, project declarations, overview panels and form reviews scroll
at compact sizes. Non-secret text fields support cursor movement and
mid-string edits; hidden secret prompts retain their own input handling.
Changes, unless --read-only is given:
| Key | Change | The vault records |
|---|---|---|
space |
Enable or disable the selected version (in details: the version selected there; in the list: the newest) | secret_update |
e |
Change that version’s metadata: enabled, content type, tags, not before, expires | secret_update |
n |
A new version of the secret, starting from the newest version’s content type and tags | secret_set |
a |
A new secret, in the storage picked (the vault file or one of its connections); a new version if a live secret has the name | secret_set |
d |
Delete the secret: soft in a recoverable vault, for good in a purgeable one | secret_delete |
u |
Recover a deleted secret (Deleted view) | secret_recover |
x |
Forget a project whose folder or manifest is gone (Projects view); the disk is not touched | project_unlink |
c |
Change the vault’s settings (view check, recovery key, storage) on the setup screens, in place of the browser | what the screens change |
n (Vaults) |
Create a vault on the setup screens | vault_create and the rest |
Every change is checked first with the vault’s own rules (names, tags,
time windows) and what the secret’s storage can express (a provider that
keeps properties per secret changes only the newest version; Azure Key
Vault cannot remove a time window), so one the vault or its provider would
refuse is never sent, and then shown for confirmation; Enter makes it,
Esc drops it. Deleting for good must be confirmed by typing the
secret’s name. Afterwards the browser reads the vault again. A value is
never typed into the browser: for n and a, confirming leaves the
screen and asks for it twice at the same hidden prompt as secret set,
then stores it and comes back; an empty value, or two that differ, store
nothing. Purging, destroying and acknowledging a truncation are not
available in the browser; nothing can be changed in a blocked vault.
A blocked vault. Vaults are opened for inspection, as audit opens
them. One blocked by an unacknowledged audit-log truncation (see audit
above) shows its audit log and a callout naming the truncation, and
nothing else: the browser never asks it for secrets, since each refusal
would be recorded. Acknowledge with sourceorrery audit --acknowledge.
Search. / filters the current view; each view keeps its own filter.
Words match anywhere in a row (all of them, in any order, case ignored).
Qualifiers narrow by one field; several of one kind mean any of them:
| View | Qualifiers |
|---|---|
| Secrets, Deleted | tag:KEY, tag:KEY=VALUE, status:enabled|disabled|pending|expired, type:TEXT (content type), expires:<30d (expires within that many days, or has expired) |
| Audit log | op:TEXT, outcome:success|denied|failure, secret:TEXT, actor:TEXT |
A qualifier for the other kind of view matches nothing. Enter keeps the
filter; Esc clears it.
f opens filter categories with counts computed from cached metadata.
Selecting another facet of the same kind replaces that qualifier; typed
queries still support same-kind OR alternatives. Matching words are
highlighted. s offers Secrets name/updated/expiry and Audit timestamp
sorting; missing dates stay last. Sorting and refresh retain the selected
object by its full identity, or clear selection if it disappears.
| Key | Action |
|---|---|
↑ ↓ / k j |
Move the selection (in details: the versions) |
PgUp PgDn |
Move by a screenful |
Home End / g G |
First / last |
Tab Shift-Tab / ← → / 1–6 |
Switch view |
Enter |
Details of the selected secret or project; open the selected vault |
Esc |
Back: close the help, the search box, the details; clear the filter |
/ |
Search |
F2 |
Contextual Actions and unavailable reasons |
f / s |
Cached filters / sorting |
i / ! |
Complete cached metadata / message details |
t |
Preview Dark, Light or Terminal; Enter applies, Esc restores |
r |
Read the vault again (on Vaults: list the files again) |
v |
Check the audit chain again |
L |
Lock now: drop the vault and wipe its key |
space e n a d u x c |
Changes (see above) |
? |
Keys and search syntax |
q / Ctrl-C |
Quit |
What the vault records: metadata is read when first shown and retained until explicit refresh or a confirmed change needs a reload. Navigation, sorting, filtering, menus, theme changes and cached inspection do not introduce vault/provider reads.
| Browser action | Audit events |
|---|---|
| Opening a vault | one vault_open, and a guard when its view check is asked |
The secret list: on opening, and on each r |
one secret_list, and one for each connection that stores secrets (its provider’s listing) |
The deleted list: the first time the Overview or the Deleted view is shown after opening or r |
the same |
A secret’s details: the first time they open after opening or r |
one secret_inspect |
| The audit log, verifying the chain, the vault’s keys, connections, view check and projects, a project’s manifest on disk, the vault list, searching, moving, redrawing, locking | none |
What is shown is a snapshot: a change made from another terminal appears
after r. The successful-load time remains visible. A failed refresh
keeps its failure state and last successful time; complete error details
remain available. Refresh and uncached detail opening display an operation
message before blocking work; neither promises cancellation while blocked.
| Theme | Env | Look |
|---|---|---|
dark (default) |
SOURCEORRERY_THEME |
The documentation site’s dark palette: warm charcoal, navy ink, callout colours for status and messages. Painted over the whole screen. |
light |
The site’s light “paper” palette, painted the same way. | |
terminal |
The terminal’s own background and named colours, as the banner uses. |
dark and light use 24-bit colour on Windows and wherever COLORTERM
says truecolor, and the nearest xterm 256 colours elsewhere (macOS
Terminal, for one). NO_COLOR turns colour off in every theme. The same
themes draw the setup screens and init’s.
The browser, init’s screens and the setup screens are the ui cargo
feature of sourceorrery-cli, on by default. A build without it
(--no-default-features --features os-keyring) has no ui command, and
setup and init print and take flags instead.
completions
Section titled “completions”sourceorrery completions bash|zsh|fish|powershell|elvishExamples
Section titled “Examples”# On a terminal: a vault on the setup screens, then a projectsourceorrery setupsourceorrery ui # add secrets (a), browsesourceorrery init # in the project's folder
# A script: the vault, its password, a secret, the manifestsourceorrery vault create development --recovery-key-out development.recovery-key \ --password-file password.txtprintf '%s' "$DB_PASSWORD" | sourceorrery secret set database-password --vault development --stdinsourceorrery init development --secret database-password
# The same vault from WSL, a container or CI: its recovery key from a fileexport SOURCEORRERY_HOME=/mnt/c/Users/me/AppData/Local/sourceorreryexport SOURCEORRERY_RECOVERY_KEY_FILE=/run/secrets/development.recovery-keysourceorrery checksourceorrery run -- ./deploy.sh