CLI configuration

Sign in and inspect

com login uses the browser authorization flow and writes the successful local profile to ~/.config/vex/config.toml. It also makes a best-effort update to your JJ author identity, using the commit author email selected under Account settings.

com login
com whoami
com settings show --format json

Add extra addresses and pick the default commit author email at Account in the web app. Each extra address must be verified before Composal will write it into new commits. com login refreshes the local JJ identity after a change; existing checkouts keep the previous user.email until you sign in again.

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

Choose an organization context

Organization-scoped CLI commands accept --org <slug> or --org org_…. An explicit flag wins; otherwise Composal reads the organization from the enclosing Composal checkout (including nested folders and linked workspaces), then uses the configured default. Outside a checkout with no default, pass --org or set a context:

com artefacts publish ./report.md
com automations list
com secrets list --org
com secrets list --org acme

Secrets still defaults to the checkout's app when neither scope flag is supplied. 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 fallback context by slug, name, or ID; inspect or clear it as needed.

com context switch <org>
com context show --format json
com context clear

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.

com settings set-default-datacenter lon1
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 VEX_API_TOKEN.
3. The local config file at ~/.config/vex/config.toml.

Do not commit or copy the local config file between machines. On Windows + WSL, the WSL CLI profile is separate from Windows desktop configuration.

Keep workspace policy with the repository

Use com ws from the main repository root to inspect or establish a checked-out workspace policy. The policy lives in .vex/workspace.toml; workspaces themselves live outside the parent checkout by default.

com ws config
com ws config --init
com ws create
com ws list

Use com ws remove <name> rather than deleting a registered workspace manually, so the repository lifecycle hooks run.

When workspaces have already been deleted by hand, or have outlived the work they were created for, com prune finds the registrations left behind and removes them.