Reference

Synopsis

cendarum run    [--project <name|id>] --env <name|id> [--only KEY,KEY]
                [--email <email>] [--shell] -- <cmd> [args...]
cendarum import [--project <name|id>] --env <name|id> [--email <email>]
                --scope shared|personal [--file <path>|-]
cendarum export [--project <name|id>] --env <name|id> [--email <email>]
                --scope shared|personal|effective
                [--format dotenv|json] [--out <path>] [--force]

Flags

Flag	run	import	export	Notes
--env <name|id>	req	req	req	Required everywhere
--scope <scope>		req	req	shared|personal for import, shared|personal|effective for export. Refused at parse time if missing, before any prompt or network
--project <name|id>	opt	opt	opt	Disambiguates a duplicated environment name
--email <email>	opt	opt	opt	Else CENDARUM_EMAIL, else prompted
--only KEY,KEY	opt			Repeatable; combined and de-duplicated
--shell	opt			Exactly one argument after --
--file <path>|-		opt		Omitted means stdin
--format dotenv|json			opt	Defaults to dotenv
--out <path>			opt	Omitted means stdout
--force			opt	Requires --out
-h, --help	req	req	req	Prints usage

req = required · opt = optional · blank = not applicable

run deliberately takes no --scope — it always injects the composed effective map (ambient < shared < personal), and a flag would imply the composition is optional. See personal overrides.

Environment variables

Variable	Default	Purpose
CENDARUM_API_BASE	https://api.cendarum.com	API base URL
CENDARUM_EMAIL	—	Account email, so you aren’t prompted
CENDARUM_DATA_DIR	per-OS path below	Override the vault directory, for isolated profiles

There is no variable for the master password, by design. A process environment is readable by anything running as the same user, so supplying one would defeat the property the tool exists to provide.

Vault file location

Platform	Path
macOS	~/Library/Application Support/com.cendarum.app/vault.bin
Linux	$XDG_DATA_HOME/com.cendarum.app/vault.bin
Windows	%APPDATA%\com.cendarum.app\vault.bin

The desktop app and the CLI share this file, and coordinate through an advisory lock so a read-modify-write from one doesn’t clobber the other’s. Note the word advisory: it keeps two cooperating Cendarum processes honest, and it is not a defence against a hostile process running as your user — see locking.

Exit codes

Code	Meaning
child’s code	run passes the child’s exit status straight through
0	import / export succeeded
128 + n	The child was killed by signal n (Unix)
127	Command not found
126	Found but not executable
2	Usage error
non-zero	Unlock or command failure; see the error codes below

Error codes

Errors print as cendarum: error: <code>, or with a hint where one exists. Rate-limited responses append the window: cendarum: error: rate_limited (retry in 42s).

The codes are stable and value-free — no error message ever contains a secret, a path derived from one, or text echoed from the server.

Code	What it means	What to do
wrong_password	The master password or Secret Key didn’t derive the expected key	Retype both. The Secret Key is checksummed, so a typo there is caught locally
key_mismatch	The server served a public key that isn’t the one your password derives	Stop. This is the substitution alarm, not a typo. See the threat model
bundle_review_required	Your account keys changed and the change needs review	Open the desktop app; the CLI has no trust-review interface
locked	The vault is locked	Unlock it
no_cached_account	This machine has no account state yet	Sign in on this device once, with your Secret Key
conflict	Someone else wrote to the environment first	Re-pull and re-apply; for import, resolve in the app
rate_limited	Too many attempts	Wait out the window shown
forbidden	You don’t have access to that environment	Ask an admin for a grant
not_found	No such project or environment	Check the name, or pass --project
personal_missing	Your client has recorded that your personal overlay exists; the server now claims it doesn’t	Stop, like key_mismatch. Open the desktop app; do not assume the shared values are the ones you meant to run with

key_mismatch deserves its own reaction, and personal_missing shares it. Everything else is an inconvenience; those two mean what the server sent you disagrees with what your own device knows, and the correct response is to stop and verify rather than retry. run, import, and export all fail closed on personal_missing — silently falling back to the shared values is exactly the substitution the alarm exists to prevent. See personal overrides.

Limits

Entries per environment	10,000
Key length	1,024 bytes
Value length	1 MiB
Note length	4,096 bytes
Encrypted payload	16 MiB

A personal overlay is the same document type as the shared payload and rides the same 16 MiB cap.