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

# Client output formats

> Plain output is for people and may improve. `--format json` is a stable contract, and this is what it promises.

Two forms.

**`--format plain`** is for people, and is **not a contract** — it may improve.

**`--format json`** is a **stable contract**, and is the one an agent or a script reads.

A command with nothing machine-readable to say takes no `--format` at all: `to11 skill` reports nothing of its own, `ui` is a screen, and `code` prints nothing by design. A bare `to11` takes `--format` for the sync it runs, and its rows are [`to11 skill sync`](#to11-skill-sync)'s.

## What holds in both forms

**Nothing goes to stdout except the answer.** Progress, warnings and errors go to stderr, so `--format json` piped into a parser stays valid even when something went wrong.

```bash theme={null}
to11 skill list --format json 2>/dev/null | jq '.[] | select(.state == "dirty")'
```

**The scope is in the output, not assumed.** Every row names its location and project, so nobody has to know which configuration produced an answer.

**Silence means nothing happened.** A sync that changes nothing prints one line saying so, rather than nothing at all — an empty terminal is indistinguishable from a crash.

**`--help` is text on every command**, never JSON: it describes a command rather than reporting anything, so there is no data in it to shape.

## What `--format json` promises

Deliberately **not the API's shape**. A chosen subset, so the API can change — fields renamed, endpoints reshaped — without breaking a script or an agent reading this output. An API field never reaches it by default; it reaches it because someone added it.

* **Additive only.** No field is removed or retyped once shipped; new ones are added at the end.
* **Absent, not null.** An unknown or inapplicable value omits the field.
* **Primitives and arrays of them** — strings, numbers, booleans, and arrays of strings. Never a nested API object, so no API shape leaks through by accident. [`action_required`](#action_required) is the one exception, below.
* **Stable ordering**, so a diff of two runs is meaningful.

## `action_required`

When it [must not prompt](https://to11.ai/docs/reference/cli/non-interactive.md#when-the-cli-does-not-prompt), a command that needs an answer prints one `action_required` object on stdout instead of asking, whatever `--format` says, and exits `1`. It is part of this contract, and the one type in it that nests, one level deep: `choices` and `next` are arrays of flat objects of strings, and `ask` is one flat object of strings. They follow the same rules — absent rather than null, additive only — and are objects because an agent acts on each choice or step as one record. [Non-interactive mode](https://to11.ai/docs/reference/cli/non-interactive.md) has every field.

## `to11 skill list`

One row per skill and target.

```json theme={null}
[{ "slug": "incident-triage", "description": "Triage a production incident",
   "state": "unchanged", "target": "claude-code", "tracking": "pinned",
   "installedVersion": 4, "resolvedVersion": 4, "labelVersion": 7,
   "path": "/home/you/.claude/skills/incident-triage",
   "location": "home", "project": "acme/sre/runbooks", "label": "latest" },
 { "slug": "house-style", "description": "How we write migrations",
   "state": "dirty", "target": "claude-code", "tracking": "label",
   "installedVersion": 2, "resolvedVersion": 4, "labelVersion": 4,
   "changedFiles": ["SKILL.md"],
   "path": "/work/api/.claude/skills/house-style",
   "location": "repo", "project": "acme/web/checklists", "label": "latest" },
 { "slug": "my-own-notes", "state": "unmanaged", "target": "claude-code",
   "path": "/home/you/.claude/skills/my-own-notes", "location": "home" }]
```

| Field | Type | Present |
| - | - | - |
| `slug` | string | always |
| `state` | string | always — one of the [states](#states) |
| `target` | string | always — the configured target this row is about |
| `location` | string | always — `home` or `repo` |
| `path` | string | always — the directory this row is about |
| `description` | string | when the platform returns one |
| `tracking` | string | `pinned` or `label`; **absent whenever no version resolved** |
| `installedVersion` | number | when something of ours is on disk |
| `resolvedVersion` | number | what configuration resolves to |
| `labelVersion` | number | what `latest` points at now |
| `project` | string | `organization/workspace/project` |
| `label` | string | `latest`, when the entry names it |
| `archivedUpstream` | boolean | when the skill is archived and a version still resolves |
| `changedFiles` | strings | on `dirty` — the files that differ from what we wrote; on `orphaned` — what stays in the directory |

An **`unmanaged`** row carries only what the client knows without reading the
directory: its name, its target, its path and its location. Never a version or
an origin — guessing would be a claim about someone else's files.

**`labelVersion` is how a pin behind `latest` shows.** The row is `unchanged`
because configuration is satisfied, and the two numbers say the rest.

## `to11 skill sync`

One row per skill and target. A skill configured for two targets is two rows.

```json theme={null}
[{ "slug": "incident-triage", "outcome": "installed",
   "diskAction": "install", "stateAction": "add",
   "target": "claude-code", "version": 7,
   "path": "/home/you/.claude/skills/incident-triage",
   "location": "home", "project": "acme/sre/runbooks", "label": "latest" },
 { "slug": "house-style", "outcome": "dirty",
   "diskAction": "none", "stateAction": "none",
   "target": "claude-code", "version": 4,
   "path": "/work/api/.claude/skills/house-style",
   "location": "repo", "project": "acme/web/checklists", "label": "latest" },
 { "slug": "audit-runbook", "outcome": "conflict",
   "diskAction": "none", "stateAction": "none",
   "target": "claude-code",
   "path": "/work/api/.claude/skills/audit-runbook",
   "location": "repo", "project": "acme/web/checklists" },
 { "slug": "legacy-migration", "outcome": "failed",
   "diskAction": "install", "stateAction": "add",
   "target": "codex",
   "reason": "the response from the platform was not what this client expects",
   "path": "/home/you/.agents/skills/legacy-migration",
   "location": "home", "project": "acme/sre/runbooks", "label": "latest" }]
```

**`outcome` says what the run meant; `diskAction` and `stateAction` say what it
did.** They are separate because doing nothing to one and something to the other
is an ordinary case rather than an exception — a skill dropped from
configuration whose directory is already gone touches no files and still loses
its record.

`outcome` is `installed`, `replaced`, `updated`, `removed`, `unchanged`,
`conflict`, `dirty`, `orphaned`, `unmanaged` or `failed`.
`diskAction` is `install`, `replace`, `uninstall` or `none`.
`stateAction` is `add`, `update`, `remove` or `none`.

**`unchanged` appears in JSON but not in plain** — a machine wants the full set,
a person wants the diff. It still carries `version`, because what is installed
is a fact whether or not this run wrote it.

**`failed` replaces the outcome, it is not one of them.** Every row whose
`diskAction` is not `none` can fail, and `reason` says why: the platform does
not publish the skill, the fetch broke, the write broke, the delete broke. A
failure never reaches a field that means something else, and a run with one
exits `1`.

**`heldBy` is what holds a `shadowed` row's name** — the path in your own skills
that already uses it. The row's `path` stays its destination.

## `to11 whoami`

```json theme={null}
{ "person": "marius@to11.ai",
  "organizations": ["acme"],
  "profile": "default",
  "credentialKind": "person" }
```

With an API key, `person` is absent and `apiKey` carries the fingerprint — never the key.

## `to11 project list`

```json theme={null}
[{ "organization": "acme", "project": "sre/runbooks", "id": "proj_a1", "name": "Runbooks" }]
```

## `to11 environment list`

```json theme={null}
[{ "slug": "prod", "id": "env_p", "name": "Production", "isDefault": true },
 { "slug": "staging", "id": "env_s", "name": "Staging", "isDefault": false }]
```

## `to11 skill import`

One row per skill folder the scan found, in the order the classification prints them.

```json theme={null}
[{ "slug": "review-checklist", "path": ".claude/skills/review-checklist",
   "target": "claude-code", "class": "differs",
   "matched": "differs from acme/web review-checklist v2",
   "outcome": "left", "location": "repo", "project": "acme/web",
   "next": "to11 skill import --keep review-checklist --yes" }]
```

`class` is `match`, `differs`, `new`, or `unlinked` for a folder in a location that is not linked. `outcome` is `adopted`, `uploaded`, `kept`, `took`, `left` or `refused`; `reason` is present on a refused row, on a `new` row whose `SKILL.md` has no description, and on an `unlinked` row. `location` is `repo` or `home`, and `project` the project it is compared with. `next` is the one command that acts on the folder from here, absent when it needs an edit first or was uploaded.

## `to11 skill store`

```json theme={null}
{ "slug": "incident-triage", "version": 4, "versionId": "pv_01M2…",
  "project": "sre/runbooks", "location": "home",
  "created": false,
  "installedTo": ["~/.claude/skills/incident-triage"] }
```

`created` distinguishes a new skill from a new version of one, which is the guard against a mistyped slug.

`pinnedIn` is the configuration file whose `version:` pin on the skill moved to this version. It is absent when the configuration follows `latest` for the skill, which is the default: a store then writes no pin.

| Field | Type | Notes |
| - | - | - |
| `installedTo` | string\[] | absent with `--no-install` |
| `pinnedIn` | string | the configuration whose pin moved; absent when it follows `latest` |

## `to11 version`

```json theme={null}
{ "version": "0.4.2" }
```

## States

One name per state, the same in `sync` and in JSON. The plain `to11 skill
list` table says what the next sync would do instead, in the words of the
`list says` column, and its summary counts with the same words. Each state in
the first table except `failed` is decided from three things — whether configuration includes the skill,
whether the state file records it, and whether anything is at the destination —
plus two comparisons between those and `--force`.

| State | `list` says | When | Sync does |
| - | - | - | - |
| `installed` | `to install` | Configuration includes it and nothing was at the destination | writes the file set |
| `updated` | `to update` | We had a record, and configuration resolves something else | writes what configuration resolves |
| `replaced` | `to replace` | `--force` took content at the destination we did not write | writes over it |
| `removed` | `to remove` | Configuration no longer includes it, or disables it, and it is ours | removes the files we wrote, then the empty directory, or just the record |
| `unchanged` | `unchanged` | Already what configuration resolves | nothing |
| `conflict` | `blocked` | Configuration includes it, and something we never wrote is at the destination | nothing — names the path, `--force` takes it |
| `dirty` | `changed` | Our directory holds changes we did not write, and configuration still asks for it | nothing — `--force` replaces it |
| `orphaned` | `orphaned` | Configuration no longer includes it, or disables it, and the directory holds files we did not write or you changed, or cannot be read | removes the files we wrote that are unchanged, leaves the rest and names it; touches nothing it cannot read; no flag removes it |
| `unmanaged` | `not ours` | A directory in a target path that was never ours and is not wanted | nothing, ever |
| `failed` | `failed` | The write, fetch or delete for this skill did not complete. `list` shows it only when it could not inspect the destination or the skill's project resolved to no id; the reason says which | the next run tries again; this run exits `1` |

The states below are decided before anything at the destination is compared.
Each is a reason a skill your configuration names is not delivered, so the row
carries the reason instead of the skill being silently absent.

| State | `list` says | When | Sync does |
| - | - | - | - |
| `disabled` | `disabled` | Configuration disables it, and the project has it | takes back a copy it installed, which that run reports as `removed`; otherwise the summary counts it and no row repeats it |
| `ambiguous` | `ambiguous` | More than one entry resolves to one slug in one location | installs none of them; exits `1` |
| `shadowed` | `shadowed` | A repository skill whose name your home location already holds in the same target | nothing — the home copy stays; exits `0` |
| `not-found` | `not found` | The project has no skill with that slug — deleted, or never there | nothing; exits `1` |
| `no-label` | `not published` | The project has the skill, but no version has been stored, so `latest` carries none; the row reads `<project> has it, but no version is stored yet` | nothing; exits `1` |
| `gone` | `gone` | `not-found` or `no-label` for a skill you picked: `{ label: … }` under an entry with no project `label` | keeps a copy it installed and its record; exits `0`; at a terminal offers to remove it; `--prune` removes the files it wrote and the line, or turns the line off when it is the file's last |
| `symlink` | `symlink` | The destination, or the target directory itself, is a symbolic link | nothing is written through a link; exits `1` for a skill configuration asks for |
| `available` | `available` | `list` only: the project an entry's picks follow has it, nothing in the location names it, takes its name or holds a recorded copy, and its target is not a link — the entry has no project `label`, so it receives only what it names | nothing, and `sync` does not mention it; `to11 link` lists it unticked |

**Something at the destination we did not write outranks the version.** A
`dirty` directory is never asked what version it holds, because the answer
cannot change what happens to it.

**A pin change needs no special state.** Pinning v4 after v7 was installed means
what is recorded differs from what configuration resolves, and the row reads
`7 → 4`. The state says *a sync will change this*, not *there is something
newer*.

**A pin behind `latest` is `unchanged`, not a state of its own.**
Configuration is satisfied, so there is nothing to do — and the version column
already shows both numbers, so a separate word would be a second way of saying
it.

## The version column, in plain output

| Reads | Means |
| - | - |
| `latest · 4` | following `latest`, holding v4 |
| `latest · 4 → 7` | v7 was stored; a sync writes 7 |
| `pinned 4` | pinned to v4, and `latest` points at v4 |
| `pinned 4 (latest: 7)` | pinned and deliberately behind |
| `pinned 2 → 4 (latest: 7)` | the pin changed and is behind; a sync writes 4 |
| `7` | on disk at v7 and nothing resolves — the project no longer has it, or your configuration dropped it |
| `—` | nothing on disk and nothing resolved |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.