Skip to main content

Authenticate CLI

Use this guide to establish and validate trading-cli authentication before running strategy, backtest, deployment, or validation workflows.

Quickstart​

Login (human auth)​

export PLATFORM_API_BASE_URL="https://api-nexus.lona.agency"
export PLATFORM_API_BEARER_TOKEN="<jwt-access-token>"
trading-cli health get

Whoami (identity/scope check)​

trading-cli bot list

Logout​

unset PLATFORM_API_BEARER_TOKEN PLATFORM_API_TOKEN PLATFORM_API_KEY

Bot Auth vs Human Auth​

Use caseCredentialEnv varNotes
Human operator in terminal or CI job with user identityJWT bearer tokenPLATFORM_API_BEARER_TOKENPreferred for user-scoped operations and invite acceptance flows.
Runtime bot automationRuntime bot key (tnx.bot.<botId>.<keyId>.<secret>)PLATFORM_API_KEYWorks for bot actor requests while preserving owner scope in validation flows.
Backward compatibilityBearer token aliasPLATFORM_API_TOKENAlias for bearer auth; prefer PLATFORM_API_BEARER_TOKEN for new setups.

Failure Troubleshooting​

Expired Token​

Expected error shape:

  • httpStatus: 401
  • code: "AUTH_UNAUTHORIZED"

Recovery:

  1. Mint a fresh bearer token from your identity provider.
  2. Re-export PLATFORM_API_BEARER_TOKEN.
  3. Re-run:
trading-cli health get

Revoked Token (Bot Key)​

Expected error shape:

  • httpStatus: 401
  • code: "BOT_API_KEY_REVOKED"

Recovery:

  1. Rotate the bot key:
trading-cli key rotate --bot-id <bot-id> --reason "replace revoked key"
  1. Update secret storage with the newly issued key.
  2. Retry the failed command with the new PLATFORM_API_KEY.

Unauthorized (Missing/Invalid Credential)​

Expected error shape:

  • httpStatus: 401
  • code: "AUTH_UNAUTHORIZED" or code: "BOT_API_KEY_INVALID"

Recovery:

  1. Check auth vars:
env | rg '^PLATFORM_API_(BEARER_TOKEN|TOKEN|KEY)='
  1. Ensure PLATFORM_API_BASE_URL is set to platform host or local loopback.
  2. Retry with request correlation:
trading-cli bot list --request-id req-cli-auth-check-001