Search Composal documentation

Search public documentation, commands, and release notes.

CLI configuration

Configure Composal CLI profiles, organization context, output formats, and local settings. Keep production and development connections separate.

Contents

Sign in and inspect

com login uses the browser authorization flow and writes the successful local profile to ~/.config/composal/config.toml.

Bash
com login
com whoami
com settings show --format json

Use com login --no-browser from a headless machine and complete the printed verification URL elsewhere. Use com logout to remove the stored login.

When you select another API origin with --api-base-url, browser login stays on that origin if the server has explicitly approved it as a frontend. Otherwise, the server uses its configured frontend address. Follow the verification URL printed by the CLI.

Browser login also sets your default organization. If you belong to one organization, it is chosen automatically. Otherwise the browser asks you to pick one, with a search box for long lists.

Choose an organization context

Organization-scoped CLI commands accept --org <slug> or --org org_…. An explicit flag wins; otherwise com uses the configured default organization. With no default, pass --org or set a context:

Bash
com verify environments list --org acme --json
com verify runs list --org acme --project my-project --json
com secrets list --org
com secrets list --org acme

Pass --app for app secrets, or --org for organization-wide secrets. Use bare --org to choose organization-wide secrets with the same inference rule. Commands addressing a particular app, deployment, CDN URI, or qualified repository keep that resource's organization. An organization override never grants access to another tenant or moves an existing resource.

Switch the default organization and Verify project with com switch. Without arguments it prompts for both; type to filter long lists. Pass a slug, name, or ID to switch without prompts.

Bash
com switch
com switch acme --project storefront
com switch acme --no-project
com context show --format json
com context clear

Verify commands that take --project use the default project when you omit the flag and the command runs against the organization that project belongs to. Changing the default organization clears the default project.

Set a datacenter default when you need one

Infrastructure-aware commands can use a saved default datacenter. Set it deliberately, inspect the result, or clear it to return to command-level selection.

Bash
com settings set-default-datacenter aws-us-west-2
com settings show --format json
com settings clear-default-datacenter

Know which configuration wins

Configuration resolves in this order:

  1. Per-command flags such as --api-base-url and --api-token.
  2. Environment variables such as VEX_API_BASE_URL and COMPOSAL_API_TOKEN.
  3. The local config file at ~/.config/composal/config.toml.

VEX_API_TOKEN remains a compatibility alias. When both token environment variables are set, COMPOSAL_API_TOKEN wins.

Do not commit or copy the local config file between machines.

For a CI job, expose a Composal API token from your secret store as COMPOSAL_API_TOKEN and pass --org and --repo explicitly. This uses token authentication without an interactive browser login. The Source Control guide has preview handoff examples and result-gating instructions.