Configuration
Config precedence, persistent files, wallet resolution, and what auth each command family expects.
Precedence Order
Configuration is resolved in this order:
- Explicit CLI flags
- Environment variables
- Stored config in
~/.peer/config.json - Built-in defaults
That precedence matters because an agent can run under a shell with stale env vars and still appear “configured”.
Persistent Files
| File | Purpose |
|---|---|
~/.peer/config.json | Persistent configuration for RPC, env, formatting, API URLs, and optional secrets |
~/.peer/checkout-sessions.json | Local cache used by checkout list/show flows |
Common Global Flags
| Flag | Meaning |
|---|---|
--env | Runtime environment |
--format | json or table |
--rpc-url | Override Base RPC |
--api-key | Curator API key for SDK-backed authenticated routes |
--indexer-key | Indexer API key |
--indexer-url | Indexer base URL override |
--market-api-key | Peerlytics API key |
--pay-api-key | Pay API key |
--base-api-url / --market-base-url / --pay-base-url | Service endpoint overrides |
--private-key / --wallet-path | Signer resolution |
--yes | Execute generic writes without staying in preview |
--debug | Verbose debug logs |
Auth Model By Surface
| Surface | Typical auth requirement |
|---|---|
quote, market, pv, indexer, oracle supports-inline, oracle validate-feeds, balance, config show/platforms/currencies, mcp | No signer required |
payee, authenticated indexer or checkout reads, some SDK-backed reads | May require API keys |
deposit, intent, vault, delegate, undelegate, transfer, checkout create/cancel | Requires signer for execution |
Wallet Resolution
The wallet helper resolves account material only when a command requires it.
Implications:
- A command can succeed without a wallet if it is read-only.
- A signer-required command fails with
AUTH_REQUIREDwhen no account can be resolved. - Read-only MCP can run without live signing material.
Stored Config Commands
The CLI exposes config helpers instead of forcing direct file edits:
peer config show
peer config set env staging
peer config unset marketApiKey
peer config reset
peer config platforms
peer config currenciespeer config unset removes a single key; peer config reset clears all stored values.
Use these for scripted bootstrapping when you want the environment to persist across sessions.
peer config currencies returns the runtime's currency catalog. peer config platforms
returns the platforms supported in the selected environment. Treat their output as
authoritative if prose disagrees.
Staging UPI
CLI 0.4.0 supports UPI in staging for protocol quotes, Curator market comparison, payee registration, and deposit/intent commands:
peer --env staging config platforms
peer --env staging quote --from INR --amount 100 --platform upiProduction and preproduction reject UPI before calling those services. Peerlytics
analytics and Peer Cash tool rail inventories are unchanged. Generic deposit and
intent writes still produce unsigned previews unless execution is explicitly enabled
with --yes.
Raw Params Override
Every command accepts --params <json> and --params-file <path> to pass a raw JSON object underneath typed flags. Explicit typed flags always win when both are present.
peer deposit create --amount 250 --params '{"retainOnEmpty":true}'
peer deposit create --params-file deposit-config.json --amount 250This is useful for SDK-level parameters that don't have a dedicated CLI flag.
Agent Recommendations
- Prefer flags for ephemeral runs and one-off corrections.
- Prefer stored config for workstation-style agents that run repeatedly.
- Prefer environment variables for secret injection in CI or server environments.
- Never assume a missing API key means a command is unsupported; it may only mean the selected route needs credentials.