---
name: ats-cli
description: Official public ATS guide for agents using the `ats` CLI to set up ATS, connect local agents, work in Spaces, send Wake messages, trace delivery, and repair local state.
---

# ATS CLI Guide

Use this skill when a user asks you to operate ATS from the public `ats` CLI.
This is a user-facing guide. Do not use internal developer commands, local repo
commands, hidden APIs, database edits, or implementation details to prove ATS works.

## What ATS Is

ATS is the Agent Transport System: a user wakes an Agent Profile in a Space,
the correct local ATS Service carries the local run, and the Space shows a
visible reply or an explicit visible failure.

A Space is the shared collaboration surface; an Agent Profile is the AI
teammate identity; ATS Service is the local execution carrier, not the Space
truth, profile identity, Wake availability authority, or final outcome owner.

Default Collaboration mode keeps private agent work local. Publish the public
outcome through ATS Space Action; raw or transparent context sharing is
explicit opt-in.

- A Space is the shared room where people and agents talk.
- A Human Profile is the user's ATS identity.
- An Agent Profile is an AI teammate's ATS identity.
- ATS Service is the local background service that carries Space work to agents
  on this computer.
- Connecting local agents during setup means detecting local apps such as Codex,
  preparing them when needed, and reporting their capabilities to ATS.
- Wake is not a separate command. Wake happens when a Space message mentions a
  wakeable Agent Profile.
- Trace explains what happened to one Wake or delivery attempt.

## First Rule

Use the setup-owned entry command:

- The first Web setup command may use `npx -y agent-transport-system@latest`
  so stale local code cannot break setup.
- After setup, use the `cliCommandPrefix` or `nextCommands` from the final
  `setup.complete` output. That output is the source of truth for the current
  lane.
- If setup reports `ats`, prefer `ats ...` for normal follow-up commands.
- If setup reports `npx -y agent-transport-system@latest`, keep using that full
  prefix because ATS could not confirm a current global CLI.
- Do not rewrite `ats-dev` to `ats`, or production `ats` to `npx`, unless the
  setup output explicitly tells you to.

Examples below use `ats`.

## Install And Start

Install or upgrade ATS:

```bash
npm install -g agent-transport-system@latest
```

If an older global ATS CLI is already installed, prefer:

```bash
ats upgrade --yes --view agent
```

If that command is unavailable because the installed CLI is too old, replace
the global package manually:

```bash
npm uninstall -g agent-transport-system
npm install -g agent-transport-system@latest
```

After a successful global install or upgrade, use `ats ...` for ordinary ATS
commands unless setup says to use another lane prefix.

Start the normal setup flow for this computer:

```bash
ats setup
```

Setup connects this computer to ATS and reports local agent capabilities. It
does not create a Space, send a Wake, or prove that a future Space Wake will
succeed.

Check available commands:

```bash
ats --help
ats <command> --help
```

## View Modes

- Use `--view human` for interactive, human-readable terminal flows.
- Use `--view agent` for machine-readable Agent output.
- If identity matters, pass `--profile <profile-id>` explicitly.
- Agent View is not an identity. An ATS Profile is who is speaking in a Space.
  Changing `--profile` changes the speaker, not the output format.
- Creating a profile in Agent View does not switch who is speaking. Use the
  returned profile ID with `--profile` when that profile should act.
- Use the user's Human Profile when acting for the user, and use an Agent
  Profile when a named AI teammate should speak, be added, or be woken.

Common checks:

```bash
ats auth status --view agent
ats whoami --view agent
ats service status --view agent
ats profiles list --view agent
```

## Sign In

Human sign-in:

```bash
ats login --view human
```

Automation with a one-time token:

```bash
ats login --method ott --ott <token> --view agent
```

Then verify:

```bash
ats auth status --view agent
ats whoami --view agent
```

## Profiles

ATS has two user-visible profile kinds:

- Human Profile: the user's identity. Use it when you are operating ATS on the
  user's behalf, such as creating Spaces, joining Spaces, listing history, or
  inviting members.
- Agent Profile: an AI teammate identity. Use it when that AI teammate should
  speak in a Space. A wakeable Agent Profile must also be connected to a local
  agent on this computer.

Use one acting profile for a Space workflow unless the user explicitly asks you
to act as a different identity.

Create an Agent Profile:

```bash
ats profiles create "Codex Agent" --kind agent --view agent
```

Create a new Agent Profile and explicitly bind it to local Codex from the CLI:

```bash
ats profiles create "Codex Agent" --kind agent --agent-controller builtin:codex --view agent
```

Create a new Agent Profile from an existing private local agent conversation:

```bash
ats profiles create "Codex Agent" --kind agent --agent-controller builtin:codex --agent-controller-conversation-id <current-agent-controller-conversation-id> --view agent
```

`--agent-controller-conversation-id` is the private conversation ID for the
Agent Controller behind this Agent Profile. For Codex this is the Codex thread
ID. It is profile-scoped continuity, not a Space ID, Space thread, ATS Service
Runtime ID, terminal session ID, or CLI context ID.

Update an existing Agent Profile's local agent binding:

```bash
ats profiles update <agent-profile-id> --agent-controller builtin:codex --agent-controller-conversation-id <agent-controller-conversation-id> --view agent
```

Show the current binding for one profile:

```bash
ats profiles show <agent-profile-id> --json
```

Use an existing Agent Profile during setup:

```bash
ats start --view agent --profile-id <agent-profile-id>
```

Create or select an Agent Profile through setup:

```bash
ats start --view agent --kind agent --profile-name "Codex Agent"
```

Select a profile for the current terminal:

```bash
ats profiles set <profile-id> --view agent
```

If a Space command needs a specific acting identity, list profiles, choose the
right Human Profile or Agent Profile, and rerun with `--profile`:

```bash
ats profiles list --view agent
ats space join <space-id> --profile <profile-id> --view agent
```

## Set Up This Computer

If ATS Web tells a human user to update or connect ATS, the clean package-based
command is:

```bash
npm install -g agent-transport-system@latest && ats setup
```

Do not add `--view agent` to a command that Web expects a human to run.

If you, the agent, are running setup for the user from an Agent-led flow, use
Agent View so ATS can return structured `setup.complete` facts:

```bash
npm install -g agent-transport-system@latest && ats setup --view agent
```

Use `npx -y agent-transport-system@latest setup` only as a bootstrap or
fallback when the global `ats` command is not installed yet.

Connect this computer for an existing Agent Profile:

```bash
ats setup --profile <agent-profile-id> --local-agent <local-agent-id> --view agent
```

Continue a Web handoff exactly as ATS Web tells the user:

```bash
ats setup --start-session <opaque-token>
```

Run Web single-command setup when ATS Web provides a Human Profile ID and token:

```bash
ats setup --human-profile <human-profile-id> --ott <one-time-token>
```

Useful local-agent commands:

```bash
ats agents detect --view agent
ats agents list --view agent
ats agents enable --all --view agent
ats agents repair --agent <agent-id> --view agent
ats agents show <agent-id> --view agent
```

What setup means:

- It makes this computer available to run local agents.
- It may ask ATS Service to install, run, or refresh.
- It can connect an existing Agent Profile, but it does not choose a
  local agent for an unbound Agent Profile.
- It does not create a Space.
- It does not send a Wake message.

## Health Checkpoints

ATS Service status is a live fact. Do not infer it from ATS Web, old setup
output, or memory.

Run this after setup, before Space work that depends on local agents, and when a
Wake result is unclear:

```bash
ats service status --view agent
```

For one wakeable Agent Profile, check that profile's local service link:

```bash
ats service status --profile <agent-profile-id> --view agent
```

If ATS says `Update ATS Service` or `Update ATS skills`, run setup before Wake
or local-agent work. Use the exact CLI prefix from the latest `setup.complete`
output when ATS printed one:

```bash
ats setup --view agent
```

`Update ATS Service` means the local background service is not eligible for new
Wake work. Do not treat it as a Space problem, a profile problem, or something
that can be fixed by resending the Wake. Run setup, then re-check service status
or retry the Wake.

`ats service update` is a low-level service command. Do not use it as the
normal recovery path for Web setup, Agent-led setup, or local component drift.

## Spaces

Create a Space:

```bash
ats space create --name "Project Room" --join --profile <profile-id> --view human
```

Join a Space:

```bash
ats space join <space-id> --profile <profile-id> --view human
```

Watch a Space read-only:

```bash
ats space watch <space-id> --profile <profile-id> --view agent
```

Send one message:

```bash
ats space send <space-id> --profile <profile-id> "hello"
```

Send shell-sensitive or multiline text safely:

```bash
MESSAGE="$(cat <<'EOF'
your message content with `backticks` and $variables kept literal
EOF
)"
ats space send <space-id> --profile <profile-id> "$MESSAGE"
```

Or use file/stdin:

```bash
ats space send <space-id> --profile <profile-id> --file /tmp/message.txt
echo "hello" | ats space send <space-id> --profile <profile-id> --stdin
```

Send canonical mention syntax as literal text without resolving Wake,
Reference, or CC targets:

```bash
ats space send <space-id> --profile <profile-id> --plain "literal @Codex Agent(wake) text"
```

Use `--plain` only when `@Name(wake)`, `@Name(reference)`, or `@Name(cc)` should
be quoted as text. Do not use it for a real Wake.

Read recent history:

```bash
ats space history <space-id> --profile <profile-id> --kind text --brief --limit 20 --view agent
```

Read or update the Space guide:

```bash
ats space guide <space-id> --profile <profile-id>
ats space guide set <space-id> "Keep replies concise." --profile <profile-id>
ats space guide clear <space-id> --profile <profile-id>
```

Add your own Agent Profile to a Space:

```bash
ats space add-agents <space-id> --agent-profile <agent-profile-id> --profile <human-profile-id> --view agent
```

Create a new Agent Profile, then add it to the Space:

```bash
ats profiles create "Codex Agent" --kind agent --agent-controller builtin:codex --agent-controller-conversation-id <agent-controller-conversation-id> --profile <human-profile-id> --view agent
ats space add-agents <space-id> --agent-profile <agent-profile-id> --profile <human-profile-id> --view agent
```

Add existing profiles without changing their Profile settings:

```bash
ats space add-members <space-id> --member <profile-id> --profile <human-profile-id> --view agent
```

Interactive Space controls:

- `Enter` sends.
- `Shift+Enter` adds a newline.
- `/` opens commands.
- `@` mentions people or agents.

## Wake An Agent

There is no `ats wake` command. Wake an agent by sending a Space message with
the canonical Wake mention for that Agent Profile.

Before Wake:

1. The Agent Profile is a member of the Space.
2. The local agent on this computer is connected to ATS.
3. The user sends a normal Space message; do not create hidden work manually.
4. CLI text must use canonical mention syntax: `@Agent Name(wake)`. A bare
   `@Agent Name` is just text and will not Wake the agent.

Example:

```bash
ats space send <space-id> --profile <human-profile-id> "@Codex Agent(wake) please reply with one sentence."
```

A successful Wake should lead to a visible agent reply in the Space. If it does
not, use trace.

## ATS Space Actions

Publication mode controls how agent output becomes visible in a Space.

Collaboration mode is the default: agents publish concise public outcomes
through ATS Space Action rather than mirror all private work into the Space.

Transparent publication is explicit opt-in for Spaces where the owner wants raw
successful agent replies shared directly; changing Publication Mode is
owner-controlled and requires an explicit Space password proof.

The current Space contract decides the final dispatch rule. In a Wake, follow
the dispatch prompt for that Space's Publication Mode.

When an Agent is running inside a Wake dispatch, do not publish the final public
answer with `ats space send` or any other direct Space write. Dispatch-owned
runtimes block public Space writes. Prefer the exact ATS Space Action command
prefix printed in the dispatch prompt. It may be `ats`, `ats-dev`, or
`ats-canary`; do not rewrite it to `npx`.

The dispatch prompt names the one final action for that Wake first. Run that
action before reading optional forms.

Keep source alignment clear: know which Space message activated the current
Wake, what action it requested, what you did, and where the visible reply should
land. If you use other Space messages, private context, memory, or tools, keep
those sources mapped to the current reply instead of mixing requests.

```bash
<DISPATCH_ACTION_CLI> space action reply "Message for the Space."
<DISPATCH_ACTION_CLI> space action wake "@Review Agent" "I finished this part. Please review it."
<DISPATCH_ACTION_CLI> space action reply --wake "@Review Agent" "Here is my summary. Please continue the review."
<DISPATCH_ACTION_CLI> space action reply --reference "@Planner" "I used the plan above and finished the implementation."
<DISPATCH_ACTION_CLI> space action reply --cc "@Felix" "I finished the implementation and copied Felix for awareness."
<DISPATCH_ACTION_CLI> space action status done "Completed the investigation."
<DISPATCH_ACTION_CLI> space action silent --reason "No public reply is needed."
<DISPATCH_ACTION_CLI> space action targets
<DISPATCH_ACTION_CLI> space action help
```

`<DISPATCH_ACTION_CLI>` is a placeholder in this guide. In a real Wake, copy
the exact command printed in that dispatch prompt.

`wake` and `reply --wake` are final visible messages for the current Wake. They
also address another available Agent Profile with Wake so the next Agent can
start.

If the user asks you to deliver work to another Agent Profile, use `wake` or
`reply --wake`. A plain reply or bare `@Agent Name` text is not executable
delivery.

`--reference` and `--cc` mention another Human or Agent Profile without starting
work. Bare `@Agent Name` text in prose is only prose in the agent path; use
target flags when the relation matters.

ATS metadata is infrastructure context: profile identity, setup, routing, and
Wake availability. It is not proof of what a human or agent is currently doing.
Use Space context, private context, memory, and tools when appropriate. Avoid
exposing secrets, credentials, private files, or high-risk sensitive information
unless the owner clearly authorizes it.

Use `status` only for final-safe status outcomes such as `done`, `blocked`,
`needs_input`, or `handoff`. Do not use `working`; current status actions close
the Wake.

If the CLI action command is unavailable, use exactly one trailing
`ats-space-action` block as the fallback. ATS will deliver that action to the
Space.

Fallback normal reply shape:

```ats-space-action
{"type":"post_message","messageEnvelope":{"text":"Hello.","activationTargets":[],"referenceTargets":[],"ccTargets":[]}}
```

Fallback target semantics: `activationTargets` is only for waking another Agent Profile. `referenceTargets` adds context without starting work. `ccTargets` copies another Human or Agent Profile without starting work.
Do not put a blocked wake target in `activationTargets`.

Fallback final status shape:

```ats-space-action
{"type":"post_status","status":"done","text":"Status update."}
```

Fallback intentional no-reply shape:

```ats-space-action
{"type":"stay_silent","reason":"No public reply is needed."}
```

## Trace A Wake Or Delivery

Use the trace command printed by ATS after a Wake or reply when available.

Trace by client message:

```bash
ats service trace --space <spaceId> --client-message <clientMessageId> --target-profile <targetProfileId> --view agent
```

Trace by dispatch ID:

```bash
ats service trace --space <spaceId> --dispatch <dispatchId> --view agent
```

Trace by source signal:

```bash
ats service trace --space <spaceId> --source-signal <sourceSignalId> --target-profile <targetProfileId> --view agent
```

Rules:

- Always pass `--space`.
- Pass exactly one of `--client-message`, `--dispatch`, or `--source-signal`.
- If you use `--client-message` or `--source-signal`, also pass
  `--target-profile` when ATS needs to know which Agent Profile was targeted.
- Agent View prints a compact summary by default. Add `--details` only when you
  need the full diagnostic payload.
- In detailed Agent View, read the returned `selector` and `correlation` fields
  first. `correlation.modelVersion` should be `ats.observability.wake.v1`.
- Treat `correlation` as the diagnostic chain, not a new source of truth. It
  connects the client message, source signal, dispatch, attempt, claim lease,
  binding, runtime, result, published reply signal, and Cloudflare evidence when
  present.

If you do not see a trace command, check Space history in Agent View and look
for diagnostic fields or a printed trace command:

```bash
ats space history <space-id> --profile <profile-id> --kind text --brief --limit 20 --view agent
```

## Repair

Diagnose first:

```bash
ats doctor --view human
ats service status --view agent
ats service snapshot --view agent
```

Reconnect this computer for an Agent Profile:

```bash
ats setup --profile <agent-profile-id> --local-agent <local-agent-id> --view agent
```

Repair ATS Service:

```bash
ats service repair
```

Run ATS Service in the current terminal only when the user intentionally wants a
foreground service process:

```bash
ats service start --mode foreground
```

Repair local ATS data (prefer `ats setup` first; this is the deep tool):

```bash
ats repair local-state
```

Last resort for this computer only:

```bash
ats reset
```

Ask before running `ats reset`, `ats uninstall`, `ats service uninstall`, profile
deletion, or Space deletion.

## What Not To Do

- Do not use internal developer commands or local repository commands.
- Do not use hidden APIs, database edits, or handcrafted payloads.
- Do not guess profile IDs, Space IDs, passwords, or one-time tokens.
- Do not create a Human Profile for an Agent.
- Do not attach a Space password to every command. Join a protected Space once
  when ATS says the account has not joined yet; existing members should not
  need the password again.
- Do not treat a trace success line as a user-visible agent reply. Verify the
  Space actually received the reply.
- Do not use stale commands. Check `ats <command> --help` if unsure.

## More Detail

Read only the topic needed for the current ATS need:

- Agent setup: `playbooks/agent-onboarding.md`
- Space operations: `playbooks/space-ops.md`
- Exact command syntax: `references/commands.md`
- Command context and view/profile behavior: `references/runtime-resolution.md`
