@constal/cli

The command-line client for the public Constal Platform API.

npm install --global @constal/cli
constal --help

Authenticate and select a namespace:

printf '%s' "$CONSTAL_API_KEY" | constal auth login --token-stdin
constal context use --namespace default
constal auth status

The CLI covers deployments, Agents and Runs, Resources and bindings, Credentials, Channels, Policies, analytics, Evals and training, Memory, customers, artifacts, stages, and tables. Run constal help <command> for exact arguments and examples.

Configuration is read in this order:

1. command-line options
2. CONSTAL_PLATFORM_URL, CONSTAL_NAMESPACE, and CONSTAL_TENANT
3. the saved context file

CONSTAL_API_KEY overrides the saved credential. Local files live under $XDG_CONFIG_HOME/constal, or ~/.config/constal when XDG_CONFIG_HOME is unset. Set CONSTAL_CONFIG_DIR to use another directory.

JSON values accept inline JSON, @FILE, or @- for stdin where the command help allows them. Credential material is accepted only through the dedicated file or stdin options and is redacted from CLI output.

See the Constal CLI documentation for complete workflows.

Multiple Constal manifests

Select an authored manifest inside a local project without changing the checkout:

constal deploy . --manifest channels/incoming/constal.channel.json --wait

The selected manifest is placed at the project root in the upload archive. Other root resource manifests are omitted. Relative entry paths remain relative to the project root. For a local Channel, AuthProvider, Policy, or Tool manifest with an omitted or null expectedCurrentDeploymentRevision, the CLI reads the current Resource through the public API and adds its deployment revision as the promotion base in the archive. A missing Resource uses a null base for its first deployment. Explicit revision pins are preserved, and ordinary Agent deployments remain unconditional. The configured namespace must match the component manifest. Git URL and prebuilt archive sources are submitted as supplied; their manifests must already include any required promotion base.

Agent manifests with a ui block

An Agent manifest may declare its web interface inline. constal deploy . then builds the Agent, packages the declared directory as a constal.ui.v1 bundle, and publishes a ui Resource pinned to the Agent revision produced by that deployment; the Agent and its UI are promoted together or not at all.

{
  "kind": "agent",
  "id": "market-landscape",
  "namespace": "default",
  "entry": "src/index.ts",
  "ui": {
    "id": "market-landscape-workspace",
    "displayName": "Market landscape",
    "source": "ui",
    "channel": { "kind": "local", "resourceKind": "channel", "id": "openai-chat-completions" },
    "access": { "mode": "public" },
    "execution": { "mode": "stateless" },
    "labels": { "app.constal.ai/primary": "true" }
  }
}

The declared ui.source directory is always archived: a .constalignore pattern that matches it or one of its parents is skipped for that directory alone, while dist, node_modules, .constal, .env* files, and symbolic links stay excluded inside it. The CLI fails before uploading when ui.source names a reserved directory, is missing or empty, or contains a nested constal.agent.json. An optional <source>/constal.ui.json inside the directory overrides bundle manifest defaults (entry worker.mjs, assets public/ with index.html fallback, durable state); it is never read as a root manifest.

The UI ships inside the Agent archive, so the compressed upload stays under the 10 MiB deployment intake limit; larger UIs use the standalone Resource API. Inline UIs support only immediate rollouts: --rollout canary and candidate builds are rejected. Removing the block later leaves the published UI untouched; delete it explicitly with constal resources delete ui <id>.

After --wait, the deployment record lists the UI under outputs, and the CLI prints UI: <url> (hash <resourceHash>) on stderr:

constal deploy . --wait --output json | jq -r '.outputs[] | select(.resourceKind == "ui") | .resource.url'