Skip to main content
Connect the installed CLI to the environment and account you want to work with. Start with a sandbox API key from the Straddle dashboard.
1

Provide an API key

Choose how the CLI receives your key:
Set STRADDLE_API_KEY in your shell or through your secret manager. Replace the placeholder locally:
This variable overrides a token saved with auth set-token. Enter keys outside agent prompts and shared scripts; shell history can retain commands that contain them.
Inspect credential presence and source:
authenticated: true means a credential is present. verified: false means this check hasn’t tested it against the API.
2

Select the environment

Use sandbox while building and testing:
Sandbox is the default. Use production with a production key when you’re ready for production operations. A configured STRADDLE_BASE_URL or base_url can override the standard host, so verify the resolved environment in step 4.
3

Set your integration type

Choose the command that matches who owns the customers and payments:For a SaaS or marketplace platform, select the embedded account for account-level work:
This selection stays in effect until changed. straddle use-account --clear returns to a context without an acting account. Direct business integrations use their key’s account and omit this step.
4

Verify context and an API read

Inspect runtime_context.environment, integration_type, and acting_account:
Then request one customer from the selected environment:
A successful response, including an empty list, confirms that the key can perform this operation. Resolve any authentication or scope error before continuing.

​
Choose an account for one command

For a platform payment read, override the saved account with --account:
The CLI applies Straddle-Account-Id by operation and integration type. Marketplace customer, paykey, and Bridge operations use platform ownership. Account-management operations take IDs in the path or body. See account scoping for the ownership rules.
Credentials live in config.toml; integration type and the saved account live in platform.toml. STRADDLE_CONFIG selects the credentials file and places platform.toml beside it. STRADDLE_PLATFORM_CONFIG selects the platform file explicitly. The --config flag changes only the credentials file.A profile applies saved flag values to one invocation. Inspect it with straddle profile show PROFILE_NAME, then use --profile PROFILE_NAME on compatible commands. profile use prints values; it doesn’t activate a persistent profile. Explicit flags override saved values.A saved account acts as an explicit --account, including on commands that reject it. Run use-account and profile inspection without --profile. Profiles can also supply sync filters or path-context; review sync completeness before using them for analysis.