CLI configuration

The wardkey CLI is configured three ways. They compose in this order, highest precedence first:

1
1. Command-line flags
2. Environment variables
3. The per-user config file at ~/.config/wardkey/config.toml

Anything you pass on the CLI always wins. Anything you export as an env var wins over the file. Anything in the file is a default the others can override.

Global flags

Available on every command:

Flag	Default	Meaning
`--api string`	`https://api.wardkey.app`	Wardkey API base URL. Point at a local API Worker for development.
`--org string`	from config file	Target org id. Overrides the `org` key in `config.toml`.
`--project string`	`default`	Target project slug. Every new org has a `default` project at bootstrap.
`--env string`	`production`	Target environment slug. The `default` project ships with a `production` environment at bootstrap.
`--json`	off	Emit JSON-shaped output instead of human-readable text. Useful in scripts.
`-h, --help`	—	Help for the command.
`-v, --version`	—	Print the CLI version and exit.

Environment variables

Var	Purpose
`WARDKEY_API`	Override the API base URL. Equivalent to `--api`.
`WARDKEY_ORG`	Default org for commands. Equivalent to `--org`.
`WARDKEY_CONFIG`	Override the config file path. Default `~/.config/wardkey/config.toml`.
`WARDKEY_KEYRING_BACKEND`	Force a specific keyring backend (e.g. `file` on headless Linux).
`WARDKEY_KEYRING_PASSPHRASE`	Passphrase for the `file` keyring backend, so it doesn't prompt.

Config file

Per-machine defaults live at ~/.config/wardkey/config.toml (or $XDG_CONFIG_HOME/wardkey/config.toml). Override the location with WARDKEY_CONFIG. Both keys are optional:

api = "https://api.wardkey.app"
org = "org_abc"

This is the right place to pin a default org so you don't have to pass --org on every command.

Pointing at a local API

For development against a local API Worker:

# One-off
wardkey login --api http://localhost:8787

# Or persist it in the config file
cat > ~/.config/wardkey/config.toml <<'EOF'
api = "http://localhost:8787"
EOF

# Or in the env
export WARDKEY_API=http://localhost:8787

Once --api is set (any of the three ways), every subsequent command — including whoami, secrets, and exec — routes there.

Switching projects and environments

Both --project and --env are global. The default project and production environment are bootstrapped on every new org, so the bare commands work out of the box. To target something else:

# A specific project
wardkey secrets list --project payments

# A non-production environment
wardkey secrets get db/password --env staging

# Combine
wardkey exec --project payments --env staging -- ./worker.sh

There's no config-file key for these yet — they're per-command via flag or env.