Configuration¶

The CLI stores configuration in ~/.ipto/config.toml and supports environment-variable overrides for CI/CD and agent workflows.

Authentication¶

Authenticate before using any command that accesses the API.

ipto login

This opens your default browser for OAuth sign-in. If a browser is not available (e.g., SSH sessions), the CLI falls back to an email/password prompt.

Pass an existing session token directly:

ipto login --token <session_token>

For non-interactive environments (CI pipelines, AI agents), authenticate with an API key:

ipto login --api-key <key>

Info

API-key authentication skips the browser flow entirely and is the recommended method for headless and automated environments.

Logout¶

ipto logout

Clears stored credentials from ~/.ipto/config.toml.

Config File¶

The CLI reads its configuration from ~/.ipto/config.toml. A minimal file looks like this:

api_url = "https://api.ipto.ai"
default_profile = "production"

Field	Type	Default	Description
`api_url`	string	`https://api.ipto.ai`	Base URL for the IPTO API.
`default_profile`	string	`"default"`	Profile used when `--profile` is not specified.

Profiles¶

Named profiles let you switch between tenants, environments, or accounts without editing config on every invocation.

[profiles.production]
api_url = "https://api.ipto.ai"
api_key = "ipto_abc_..."

[profiles.staging]
api_url = "https://staging-api.ipto.ai"
api_key = "ipto_xyz_..."

Use a specific profile:

ipto datasets list --profile staging

Or set a default:

ipto config set default_profile staging

Tip

Keep one profile per environment (production, staging, dev) so you never accidentally mutate the wrong tenant.

Environment Variables¶

Environment variables take precedence over values in the config file. This is useful for CI/CD pipelines and containerized deployments.

Variable	Overrides	Description
`IPTO_API_KEY`	`profiles.<name>.api_key`	API key for authentication.
`IPTO_API_URL`	`api_url`	Base URL for the IPTO API.
`IPTO_PROFILE`	`default_profile`	Profile name to use.

Example:

export IPTO_API_KEY="ipto_abc_your_key_here"
ipto datasets list

Output Format¶

Control how command output is rendered with the --output flag:

ipto datasets list --output json
ipto datasets list --output table
ipto datasets list --output yaml

Format	When to use
`table`	Human-friendly columns and borders. Default in interactive terminals.
`json`	Machine-readable. Pipe into `jq`, scripts, or other tools.
`yaml`	Human-readable structured output. Useful for config review.

Auto-Detection¶

The CLI automatically detects whether stdout is a TTY:

TTY (interactive terminal) --- defaults to table.
Non-TTY (piped or redirected) --- defaults to json.

This means scripts and AI agents get JSON by default without any extra flags:

# Returns JSON because stdout is piped
ipto datasets list | jq '.[0].id'

Agent-friendly by design

When an AI agent invokes ipto commands, stdout is typically not a TTY. The CLI will automatically emit JSON, so agents always receive structured, parseable output.

FAQ¶

Where is the config file stored?

The default location is ~/.ipto/config.toml. You can override this by setting the IPTO_CONFIG_DIR environment variable:

export IPTO_CONFIG_DIR=/opt/ipto
ipto datasets list

How do I reset my configuration?

Delete the config directory and re-authenticate:

rm -rf ~/.ipto
ipto login

Can I use multiple API keys at the same time?

Yes. Define each key in a separate profile and switch with --profile:

ipto datasets list --profile production
ipto datasets list --profile staging

Or set IPTO_PROFILE per command in a script:

IPTO_PROFILE=staging ipto datasets list