Configuration & Flags
Global flags, the config file and environment variables, and the order they are applied in.
Global flags
These flags can be placed before any subcommand:
| Flag | Description |
|---|---|
--json | Print the raw JSON returned by the API instead of the default table/text format |
--quiet, -q | Print only the essentials (list commands print IDs only) — handy for scripting |
--project <id> | Override the current project context; takes precedence over the config file and PADDI_PROJECT |
--api-base <url> | Override the API address; takes precedence over PADDI_API_BASE and the config file |
--version, -V | Print the version |
--help, -h | Show help (available on any command or subcommand) |
Output formats
- Default: list commands print an aligned table; single-resource commands (such as
spec viewandrequest view) print readable text. --json: prints the raw JSON returned by the backend, ready to pipe into tools likejq. Most commands pass the API response straight through; the exception isspec info, whose JSON is metadata re-serialized on the client (fields mirror theSpecstruct, andcontentis always an empty string).--quiet: list commands print only each row's ID; create/modify commands (such ascapture createandspec download) skip the confirmation message and print only the key value (an ID or a file path).
Config file & environment variables
Settings are resolved in this order: flags > environment variables > config file > defaults.
Config file
The default location is $XDG_CONFIG_HOME/paddi/config.toml; if XDG_CONFIG_HOME is unset it falls back to <home directory>/.config/paddi/config.toml (on every platform, Windows included). Set PADDI_CONFIG to override the path entirely.
paddi workspace switch / paddi project switch write to this file. You normally don't need to edit it by hand; the format is:
api_base = "https://api.paddi.app"
[context]
workspace_id = "ws_123"
project_id = "proj_456"Environment variables
| Variable | Description |
|---|---|
PADDI_TOKEN | Supply an access token directly, bypassing the OS credential store and disabling automatic token refresh. Best for CI and non-interactive environments |
PADDI_CONFIG | Override the config file path |
PADDI_API_BASE | Override the API address |
PADDI_PROJECT | Override the current project context |
context.workspace_id has no matching flag or environment variable. It can only be set with paddi workspace switch, or updated implicitly when paddi project switch selects a project that belongs to a different workspace.