> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Command line

> The cosmon CLI — check the connection, run a task from the shell, and list the conversations your runs left behind.

Installing the SDK also installs the **`cosmon`** command — the fastest way to
check your setup and to fire a one-off task without writing any Python. It's the
same client under the hood, so anything the CLI does you can also do from
[Python](/sdk/python-reference).

```bash theme={null}
pip install cosmon-agent-sdk   # installs the `cosmon` command
```

<Note>
  The CLI is **headless** — it can't answer an `ask_user`, so it always runs the
  agent unattended (questions are never offered; the agent proceeds on its own
  judgment). For interactive runs where you answer the agent's questions, use the
  [Python handlers](/sdk/guide#attended-vs-unattended).
</Note>

## `cosmon doctor`

Check that the app is reachable, you're signed in, and the agent runtime is
ready. Run this first whenever something isn't connecting.

```bash theme={null}
cosmon doctor
```

A healthy check prints each step and the agents your app exposes:

```text theme={null}
Cosmon Agent SDK — connection check

  descriptor (default): ~/Library/Application Support/nexus/mcp-gateway.json
  ✓ reached the app
  ✓ signed in (you@company.com)
  ✓ agent runtime ready
  ✓ tool server ready
      agents: nexus, solidworks, abaqus, fluent, ansys_mechanical, comsol
      model:  claude-sonnet-5

Ready. Try:  cosmon run "what can you do?"
```

Any line marked `✗` names what to fix — check that the app is open, you're
signed in, and **Settings → Developer access** is on. `doctor` exits `0` only
when the runtime is ready; otherwise it exits `1`, so it drops straight into a
CI readiness gate.

## `cosmon run`

Run one task. By default it **streams the work** — the answer to stdout, tool
steps and `[agent]` speaker labels to stderr — so you can pipe the answer while
still watching progress on your terminal.

```bash theme={null}
cosmon run "mesh and solve" --agent abaqus
cosmon run "what can you do?" --agent nexus -q
cosmon run "compare these revisions" --agent solidworks \
    --attach v7.sldprt --attach v6.sldprt
```

<ParamField path="prompt" type="string" required>
  The task, as a single positional argument. Quote it.
</ParamField>

<ParamField path="--agent NAME" type="string">
  The platform agent — e.g. `solidworks`, `abaqus`, `fluent`. Omit for the
  default agent. `cosmon doctor` lists the agents your app exposes.
</ParamField>

<ParamField path="--attach PATH" type="string">
  Attach a file to the prompt (read on the machine running the app). Repeatable —
  pass `--attach` once per file. Relative paths resolve against your working
  directory; a missing file fails before the agent runs.
</ParamField>

<ParamField path="-q, --quiet" type="flag">
  Print only the finished transcript in one block (tool steps inline as
  `▶ <step>` lines) instead of streaming it live. Use it when you want just the
  result, e.g. `answer=$(cosmon run "..." -q)`.
</ParamField>

<ParamField path="--auto-approve" type="flag">
  Approve confirmation requests, **including dangerous ones**. Without it the CLI
  auto-declines dangerous actions (approve safe, decline dangerous) — the same
  safe default as an unattended Python run. See the warning below.
</ParamField>

<Warning>
  `--auto-approve` approves **every** confirmation gate the agent raises, including
  destructive operations (deleting bodies, overwriting files). Use it only for
  runs you fully trust and control — never on untrusted prompts. It's the shell
  equivalent of `on_confirm=lambda c: True` in Python.
</Warning>

The streaming layout is exactly what `.text(live=True)` renders in Python:

```text theme={null}
▶ Open bracket.sldprt

▶ Run static structural study

The peak von Mises stress is 187.4 MPa, at the inner fillet of the mounting lug.
```

`run` exits `0` on success and `1` if the run fails (printing `error: <reason>`
to stderr) — so `cosmon run ... && deploy` chains correctly.

## `cosmon chats`

List the conversations your scripts left on the server — SDK-owned only, never
the app user's own chats — newest first.

```bash theme={null}
cosmon chats
```

```text theme={null}
9f3c…  2026-07-20T15:04:11Z  Static study on bracket.sldprt
2a71…  2026-07-19T09:22:03Z  Mesh convergence sweep
```

Each row is `id  updated_at  title`. Resume a conversation from Python with
`client.session(id="9f3c…")` (see [multi-turn sessions](/sdk/guide#multi-turn-sessions)).
Prints `No SDK conversations on the server.` when there are none.

## Discovery & the descriptor

The CLI finds your running app the same way the library does: the app writes an
`mcp-gateway.json` descriptor while Developer access is on, and the SDK reads it
automatically. Point at a different one with the `COSMON_SDK_DESCRIPTOR`
environment variable (a dev build's data dir differs — `doctor` prints the path
it used):

```bash theme={null}
export COSMON_SDK_DESCRIPTOR="$HOME/Library/Application Support/nexus/mcp-gateway.json"
cosmon doctor
```

## Next steps

<CardGroup cols={2}>
  <Card title="Python reference" icon="code" href="/sdk/python-reference">
    The full library surface — clients, runs, handlers, streaming, and errors.
  </Card>

  <Card title="Examples" icon="list-check" href="/sdk/examples/one-shot-run">
    Runnable scripts for every capability — copy, run, adapt.
  </Card>
</CardGroup>