Documentation / CLI / Configure

Install and configure the CLI

Configure a Platform API origin, namespace, tenant restriction, secure API-key source, and stable automation output.

Before you begin

Obtain a Constal API key with only the actions required for your work. Know the namespace you intend to operate. Do not place a key in a command argument, repository, shell history, package manifest, or CI log.

Steps

  1. Install the CLI from npm and confirm the installed version:
sh
npm install --global @constal/cli
constal --version
  1. Store a key with a hidden prompt, or pipe it through stdin:
sh
printf '%s' "$CONSTAL_API_KEY" | constal auth login --token-stdin
  1. Select the default namespace and, when administrative policy requires it, a tenant restriction:
sh
constal context use --namespace production --tenant acme
  1. Run constal auth status. The command checks access through the selected namespace's public Agents endpoint rather than merely reporting that a token exists.
  2. Use constal context show to inspect the effective origin, namespace, tenant restriction, and credential source. It never prints the API key.
  3. Override stored values with CONSTAL_PLATFORM_URL, CONSTAL_NAMESPACE, CONSTAL_TENANT, or per-command flags. CONSTAL_API_KEY takes precedence over the credentials file.

Configuration is stored separately from credentials. Files are written atomically with owner-only permissions under the platform configuration directory; set CONSTAL_CONFIG_DIR when an isolated automation environment needs a different location.

Verify

Run constal agents list --output json. Confirm the request reaches the intended namespace and returns only authorized Agents. Then run constal auth logout in a disposable environment and verify authenticated commands fail without echoing the removed key.

Next steps

Read CLI workflows and automation, then choose the CLI guide in Agents, Runs, Resources, Credentials, or another product section.