CLI-first foundation

Atlas CLI Preview

Explore the future language of Atlas’s governed sales assistant with deterministic fixtures and a safe REST placeholder. Learn the workflow now; execute nothing by accident.

Local install Human + JSON output Zero domain writes Contract #358

Preview and mock only — no real Atlas action is executed. Success output proves the CLI contract and fixture renderer, not that CRM, tasks, EKB, proposals, or assistant runs executed.

01 · Quick start

Three minutes to a truthful preview

Start in mock mode. It is offline, deterministic, and safe to repeat. The preview notice is intentional: fixture behavior must never look like a live Atlas capability.

Install dependenciesFrom the repository root, use Bun to link the workspace packages.
Inspect the languageOpen help and choose a representative sales action.
Exercise a stateRun the same scenario in readable and JSON modes.

# Repository root
bun install
bun run atlas --help

# Deterministic, offline, no side effects
bun run atlas tasks list --mock empty
bun run atlas proposal confirm proposal_demo_001 \
  --mock confirmation-required --json

02 · Installation

Local by design

The CLI package is private and workspace-local. Hosting this manual does not publish the CLI to a registry or enable any real Atlas action.

Run from the repository

bun install
bun run atlas --help

Optional local command link

cd packages/atlas-cli
bun link
atlas --help

If your machine already has a command named atlas, keep using bun run atlas rather than replacing it.

03 · Configuration

Save the address, not the secret

The base URL may be saved. Access tokens may not. Remote endpoints require HTTPS; plain HTTP is accepted only for loopback development.

# One invocation; highest precedence
bun run atlas assistant status --base-url https://atlas.example.test

# Environment override
export ATLAS_BASE_URL=https://atlas.example.test

# Save only the non-secret URL
bun run atlas config set base-url https://atlas.example.test
bun run atlas config get base-url

Precedence	Source	Saved?
1	`--base-url`	No
2	`ATLAS_BASE_URL`	No
3	`~/.config/atlas/config.json`	Non-secret URL only, mode 0600
4	`http://127.0.0.1:8787`	Built-in local default

Credential posture. A future scoped token is read only from ATLAS_ACCESS_TOKEN. The preview never writes it to config, prints it, or treats its presence as proof of server authentication.

04 · Command reference

One language for people and agents

Each command will eventually map to one governed REST capability. Today, mocks are deterministic and protected REST routes return a typed non-execution result.

Auth & configuration

atlas auth status
atlas config get base-url
atlas config set base-url <url>

Shows local posture without exposing credentials. Only the base URL is persisted.

Assistant lifecycle

atlas assistant run <instruction>
atlas assistant status [run-id]
atlas assistant follow <run-id>
atlas assistant cancel <run-id>
atlas assistant continue <run-id> [input]

No run is created. Status without a run ID reaches the public preview endpoint.

CRM customers

atlas crm customers list
atlas crm customers show <customer-id>

Representative org-scoped reads using fictional fixtures.

Tasks & suggestions

atlas tasks list
atlas suggestions list

Preview empty, success, permission, and failure behavior.

Enterprise knowledge

atlas ekb search <query>

Citation-shaped mock metadata; no EKB, Vectorize, or model call.

Proposal decisions

atlas proposal inspect <proposal-id>
atlas proposal confirm <proposal-id>
atlas proposal reject <proposal-id>

Confirmation and rejection are explicit. Preview commands never mutate a proposal.

Global options

Option	Purpose
`--mock <scenario>`	Use an offline deterministic fixture.
`--json`	Emit the stable `assistant.v1.preview` envelope.
`--base-url <url>`	Override the REST base URL for one invocation.
`--idempotency-key <key>`	Name a repeatable preview request.
`--help`	Show top-level, group, or command help.

05 · Deterministic mocks

Practice every important outcome

Scenario	Result state	What it proves
`success`	completed	Readable and structured success output.
`empty`	completed + `items: []`	Truthful empty collections.
`forbidden`	forbidden	A role boundary is visible and typed.
`confirmation-required`	awaiting_confirmation	No consequential change before human review.
`rejected`	rejected	A human rejection is a final outcome.
`retryable-failure`	retryable_failure	Automation may safely retry later.
`terminal-failure`	terminal_failure	Retrying unchanged input will not help.
`repeated`	completed / already_applied	The same key returns the same result with no duplicate effect.

bun run atlas tasks list --mock success
bun run atlas tasks list --mock empty --json
bun run atlas ekb search "pricing policy" --mock forbidden
bun run atlas proposal confirm proposal_demo_001 \
  --mock repeated --idempotency-key onboarding-demo

06 · Confirmation flow

A proposal is not a write

Atlas preserves the human decision between intention and consequence. The preview shows the shape of that pause without performing the action.

1 · ProposeDescribe the intended change and evidence.

2 · InspectReview authority, expiry, and current state.

3 · DecideConfirm or reject explicitly.

4 · Final stateReturn one attributable, idempotent outcome.

$ bun run atlas proposal confirm proposal_demo_001 \
    --mock confirmation-required

ATLAS CLI PREVIEW · no real Atlas action was executed

proposal.confirm → awaiting_confirmation
Confirmation: confirm_demo_001
Review the proposed change before confirming.
Nothing changes until a human explicitly confirms.

Do not script around exit code 4. It means “awaiting human confirmation,” not “failed; retry automatically.”

07 · JSON & exit codes

Stable enough to automate the preview

Use --json when another program consumes the result. These fields are stable inside this preview contract; they are not yet the approved production #350 catalog.

{
  "schema_version": "assistant.v1.preview",
  "command": "tasks.list",
  "status": "completed",
  "request_id": "req_mock_tasks_list_empty",
  "data": { "items": [] },
  "error": null,
  "confirmation": null,
  "meta": {
    "preview": true,
    "mock": true,
    "idempotency_key": "preview-demo-key"
  }
}

Exit	Meaning	Automation posture
0	Completed, empty, or already applied	Read `status` and `data`.
2	Usage or validation error	Fix input; do not retry unchanged.
3	Unauthenticated or forbidden	Check identity; never broaden authority automatically.
4	Awaiting confirmation	Pause for a human decision.
5	Rejected	Record the human decision; stop.
6	Retryable failure	Retry with bounded backoff and the same key.
7	Terminal failure	Inspect the error; do not retry unchanged.
130	Interrupted	Inspect status before continuing.

08 · Security posture

Authority stays on the server

Tenant and role are not CLI inputs. Protected placeholders derive both from a verified Atlas identity.
Tokens are environment-only. ATLAS_ACCESS_TOKEN is never written to config, output, fixtures, or logs.
Remote transport is HTTPS-only. HTTP is accepted only for loopback development.
Redirects are refused. Credential-bearing requests are not followed to another host.
Execution is disabled. Placeholder routes never call a model, pillar binding, or datastore.
Requests remain attributable. The Worker records request ID, verified org, verified role, command, and non-execution result—never the credential.

# Presence only; token value is never printed
ATLAS_ACCESS_TOKEN=... bun run atlas auth status

# The server still decides whether identity is valid
bun run atlas tasks list --base-url https://atlas.example.test

09 · Preview limitations

What this does not prove

No production capability is claimed. The CLI is locally installable, fixtures are deterministic, and the REST shell is wired. Real delegated credentials, assistant runs, SSE, CRM/tasks/EKB execution, proposal mutation, MCP compatibility, CLI package publication, runtime deployment, and cross-surface final-state parity remain separate approved stories.

The final product CLI remains issue #277. The action catalog remains #350. Delegated credentials remain #274. Runtime and real REST behavior remain #351–#353. This foundation supplies a tested language and safe integration seam; it does not silently complete them.

10 · Troubleshooting

Errors should tell the truth

Symptom	Likely cause	Action
`command not found: atlas`	No local link	Use `bun run atlas`, or run `bun link` in the CLI package.
`invalid_usage`	Missing argument or option	Run the same command with `--help`.
`authentication_required`	No verified Atlas identity	Use mocks now. Delegated tokens remain #274.
`preview_action_not_implemented`	Real execution intentionally disabled	Do not interpret this as a product outage.
`preview_timeout`	Server unavailable or delayed	Check the base URL, then retry safely.
Remote HTTP URL refused	Unsafe cleartext endpoint	Use HTTPS or a loopback address.
Malformed config	Config edited manually	Repair the Atlas config, then set the URL again.