> ## 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.

# CLI errors and exit codes

> What a to11 failure looks like, which exit code it carries, and what keeps working when one happens.

An agent runs these commands unattended, so a failure has to be legible to a program as well as to a person.

## Exit codes

**By default there are two.** A caller branches on *worked* or *did not*, and which kind of failure it was is in the message.

| Code | Meaning |
| - | - |
| `0` | Did what was asked |
| `1` | Did not — network, credentials, the platform does not publish a skill you configured, two projects publish one skill into one target, a write failed, or the command line was wrong |

[Hook modes](https://to11.ai/docs/reference/cli/commands.md#refresh-hook-modes) always exit `0` whatever happens: a refresh does not get a vote on whether your work proceeds.

`to11 ui` exits `0` when you finish or quit, and `1` when it stops on something it cannot use — including running without a terminal.

An [`action_required`](https://to11.ai/docs/reference/cli/non-interactive) answer exits `1`. Its `status` field says that it is one, so no separate code is needed: `2` and `3` belong to `--detailed-exitcode`.

Ctrl-C during [`to11 link`](https://to11.ai/docs/reference/cli/commands#ctrl-c), or the link a bare `to11` runs, exits `1` with `error: cancelled` and names the question it stopped at.

### Detailed exit codes

`to11 skill sync --detailed-exitcode` splits the outcome. **Only when asked for** — without the flag, `sync` exits `0` or `1` like everything else.

| Code | Meaning |
| - | - |
| `0` | Nothing differed. The machine already matched its configuration |
| `1` | Error — the run failed |
| `2` | Something differed, and nothing failed. Installed, replaced, updated, removed, or left alone because you changed it |
| `3` | The command line was wrong |

**`3` exists because `2` took the meaning `1` used to carry for it.** With detailed codes on, a non-zero exit is ambiguous unless a bad flag is distinguishable from a real failure — a script that treats `2` as drift and `1` as broken would otherwise read a typo as a broken platform and start alerting.

A build step can tell from the code whether the sync had anything to do:

```bash theme={null}
$ to11 skill sync --detailed-exitcode
↑ house-style v2 → v4
$ echo $?
2
```

`0` means the machine already matched its configuration, `2` means the sync changed it or left something that still differs, and `1` means the run failed. To see what a sync would change without running one, use `to11 skill list`.

**Skipped counts as differing, not as failing.** A skill you edited on disk means the machine does not match its configuration, and a build step should see that; but nothing went wrong, so it is not `1`.

**It is opt-in** because a non-zero exit on a successful run breaks every script that does not know about it.

## What an error says

Every error names three things: **what failed, where, and what to do about it.**

```text theme={null}
error: cannot reach api.to11.ai
  your skills are unchanged and your agent keeps working
  retry, or check your connection
```

```text theme={null}
error: not configured
  looked in ~/.to11/skills.yaml and /work/api/.to11/skills.yaml
  run `to11` to link this location and fetch its skills
```

```text theme={null}
error: /work/api/.to11/skills.yaml is not readable
  line 7: mapping values are not allowed here
  fix the file — we will not fall back to your home config, because that
  would silently give you fewer skills than the repository intends
```

A value of the wrong type is named by where it sits in the file, what it should be, and what it is: `line 8: projects[0].skills.manage-skills.disabled should be true or false, not a map`.

**No stack traces**, ever. A panic is a defect in this CLI, and printing our internals at you asks you to debug our code.

Everything above goes to **stderr**, so `--format json` on a failing command still parses.

## Partial failure

**Locations fail independently.** One location reconciling while the other cannot is reported as exactly that, and the exit code is `1` because something was asked for and did not happen:

```text theme={null}
home   2 installed, 1 updated
repo   error: no access
1 of 2 locations failed
```

**Each file is written whole or not at all.** Files land in place, one at a time, so nothing ever reads half of one. A skill that fails part-way can leave the destination holding some files from the new version and some from the old. The run records what is there and reports the skill as failed, so running `to11 skill sync` again repairs it — no `--force`, and nothing calls your own directory a conflict. A location that fails leaves every skill it had not yet reached untouched.

## Degraded beats broken

When something breaks, less still beats nothing — so failure has a shape:

* **A fetch that fails changes nothing.** Previously installed skills stay exactly as they are, and your agent keeps working with what it has.
* **An expired credential is an error, not a wipe.** Nothing is removed on the assumption that access was lost: that is indistinguishable from a network problem, and the recovery from guessing wrong is losing every skill at once.
* **An unreadable repository config is an error, not a fallback.** Silently resolving from your own config alone would install fewer skills than the repository intends, without saying so.
* **A skill you edited is left alone, not overwritten** — the row reads `dirty`. The recovery is yours to choose: commit it with `to11 skill store`, or discard it with `to11 skill sync --force`.
* **Two projects publishing one skill name installs neither, and exits `1`.** One directory cannot hold both, and picking one would depend on the order the projects appear in your config. The run names both projects and the skill, leaves whatever is already at that directory alone, and every other skill in the run is installed normally. Anything already installed there stays installed, and stays recorded — a skill your config asks for twice is not a skill your config dropped. This is the one warning-shaped outcome that still fails the run: no flag resolves it, so a `0` would report success for a sync that installed fewer skills than you asked for. Give one project a different [prefix](https://to11.ai/docs/reference/cli/configuration.md), or name the skill under one project.

## Failing while nobody is watching

An automatic refresh has no terminal to print to. So:

* It **exits `0` regardless.**
* It **says nothing, and leaves no note behind.** Nothing about a failed refresh is stored for a later command to report.
* It **never retries in a loop.**

**`to11 skill sync` performs the same reconciliation and reports what that run finds** — what is in sync, what conflicted, what it updated, and anything it could not do.

## Common failures

| Message | Usually means | Do |
| - | - | - |
| `not configured` | Neither location has a `skills.yaml` | `to11`, which links this location and syncs it |
| `your credential was refused` | Your sign-in lapsed, or `TO11_API_KEY` is wrong | `to11 login` to sign in again; on a machine without a person, fix `TO11_API_KEY`. Nothing was removed |
| `no access` | The credential cannot reach that project | Ask whoever administers the organization |
| `unknown key … in configuration` | A typo in `skills.yaml` | Fix the spelling — the error names the key |
| `… is not ours — use --force` | A directory the CLI did not write occupies a skill's path | Move it, or `to11 skill sync --force` to take it |
| `changed on disk` | You edited an installed skill | `to11 skill store` to keep it, or `--force` to revert |
| `… is no longer configured; what we did not write or you changed stays` | Your configuration stopped asking for that skill or that target. The files the CLI wrote are gone; the ones listed are yours, or ones you changed | No flag removes them. The row is reported on every sync while the directory holds anything; the first sync that finds it empty removes it and its record |
| `… is in more than one of your organizations: …` | A `workspace/project` that several of your organizations have, with nothing naming one | `--organization <slug>`, `TO11_ORGANIZATION`, or `organization:` in the file — see [Naming a project](https://to11.ai/docs/reference/cli/commands.md#naming-a-project) |
| `… needs a signed-in person, and this run uses TO11_API_KEY` | The platform does not answer that request for an API key | `to11 login` |
| `you have no permission to read the projects of <slug>` | That organization refuses your credential: it is configured, or named, but not available to you | Name another organization |
| `… is in both …` / `… is in neither …` | This repository's and your home `skills.yaml` name two organizations, and the project is in both or in neither | `--organization <slug>` |
| `configuration is version N` | The file was written by a newer CLI | Upgrade the CLI |
| `unknown option "-format"` | A single-dash long option | Write `--format` — long options take two dashes |


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