# CLI configuration

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

## Sign in and inspect

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

```sh
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:

```sh
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.

```sh
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.

```sh
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](/docs/verify/source-control#cli-ci) has preview handoff examples and result-gating instructions.