Atlas CLI and REST

Release status

• MCP server: ready on staging. It publishes eleven governed tools; see the MCP server guide.
• CLI source: ready on the current staging source. Every command in the reference below exists in the current source.
• Downloadable CLI: atlas-cli-v0.1.0-staging.3. This archive predates customer search and customer creation. Build from source to use atlas customer search and atlas customer create …, or wait for the next archive.
• Production: not claimed by this update. Point the CLI at https://atlas.staging.forth.ai.

Quick start

shasum -a 256 -c SHA256SUMS
tar -xzf atlas-cli-<tag>-darwin-arm64.tar.gz
./atlas version
./atlas config set base-url https://atlas.staging.forth.ai
./atlas auth login
./atlas profile read <customer-id>
./atlas library search "warranty terms" --limit 5

atlas version prints the release tag and source SHA. Both must match manifest.json from the same release.

Installation

The private GitHub Release contains atlas-cli-<tag>-darwin-arm64.tar.gz, atlas-cli-<tag>-darwin-x64.tar.gz, manifest.json, and SHA256SUMS.

1. Download the archive for your Mac plus SHA256SUMS into one directory.
2. Run shasum -a 256 -c SHA256SUMS. Stop if any line is not OK; delete the files and download again.
3. Extract the archive and move atlas to a directory on PATH that only you can write to.
4. Run atlas version and compare the tag and source SHA with manifest.json.

Linux and Windows are not supported by the archives. On those platforms, run from source and pass the token through ATLAS_ACCESS_TOKEN.

Configuration

atlas config set base-url https://atlas.staging.forth.ai
atlas config get base-url
atlas auth login      # prompts for a token without echo, stores it in macOS Keychain
atlas auth status     # shows which token source is active, never the token
atlas auth logout

Mint the token in the Atlas portal; the MCP guide shows the request. Remote base URLs must be HTTPS. HTTP is accepted for loopback only.

Command reference

Arguments in angle brackets are required. Every command below sends one REST request to the configured base URL and prints the response envelope as JSON.

Local commands with no REST call: atlas version, atlas config set|get base-url, atlas auth login|status|logout.

Propose, confirm, reject

1. Propose with a key you choose: atlas customer create propose "Acme" --idempotency-key acme-1. The response is awaiting_confirmation and carries confirmation.id.
2. Inspect: atlas customer create inspect <id>. Check intended_*, evidence, and expires_at.
3. Decide with a second key: atlas customer create confirm <id> --idempotency-key acme-1-confirm, or reject.
4. Re-running a confirm with the same key returns the original result with meta.repeated: true and no second effect.

Proposals expire 15 minutes after creation. Confirming an expired or rejected proposal returns conflict. Task proposals follow the same steps with atlas task ….

REST without the CLI

Send the same requests from any HTTP client. Base URL: https://atlas.staging.forth.ai.

curl -sS https://atlas.staging.forth.ai/assistant/v1/actions/crm.customers.search \
  -H "Authorization: Bearer $ATLAS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"q":"Acme","limit":5}'

curl -sS https://atlas.staging.forth.ai/assistant/v1/actions/crm.customer_profile.create \
  -H "Authorization: Bearer $ATLAS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: acme-1" \
  -d '{"name":"Acme","country":"SG"}'

curl -sS -X POST https://atlas.staging.forth.ai/assistant/v1/proposals/<id>/confirm \
  -H "Authorization: Bearer $ATLAS_ACCESS_TOKEN" \
  -H "idempotency-key: acme-1-confirm"

Request bodies use the field names from the MCP tool inputs: customer_id, q, query, limit, type, source_id, name, contact, email, country, industry, customer_type, profile_gap_code, title, due_at, assignee_email, suggestion_id.

Response envelope (atlas.action.v1)

{
  "schema_version": "atlas.action.v1",
  "action": "crm.customer_profile.create",
  "status": "awaiting_confirmation",
  "request_id": "…",
  "data": { "proposal": { "id": "…", "state": "pending", "expires_at": "…", "...": "…" } },
  "confirmation": { "id": "…", "summary": "…", "expires_at": "…" },
  "meta": { "catalog_version": "…", "principal_kind": "…", "idempotency_key": "acme-1", "repeated": false }
}

status is one of completed, awaiting_confirmation (HTTP 202), forbidden, rejected, conflict, retryable_failure, terminal_failure. Failures carry error.code and error.message instead of data.

Output and exit codes

stdout is the JSON envelope, one document per command. --pretty indents it. Diagnostics go to stderr. There is no generic --yes; confirmation is always a separate command.

Token handling

• Never pass a token as a command argument. Use atlas auth login or ATLAS_ACCESS_TOKEN. The CLI never prints or logs it.
• In CI and scripts, set ATLAS_ACCESS_TOKEN from the runner's secret store. It takes precedence over Keychain.
• Mint tokens with only the scopes the job needs. Tokens live at most 30 days and can be revoked by an admin.
• Expiry and revocation are decided by the server. The CLI returns the envelope and exits 3.

No analytics, remote fonts, external scripts, or secret-bearing assets are included in this manual.

Troubleshooting