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

# Simple AI CLI Command Reference

> The simple commands you use day to day: signing in, creating and publishing agent projects, managing organization resources, and updating the CLI.

`simple` is the command-line tool in `@simple-ai-lab/cli`. It signs in as you, with your dashboard account, and every command runs with your own permissions. Install it and make your first publish with the [quickstart](https://docs.usesimple.ai/cli/quickstart.md); [Agent projects](https://docs.usesimple.ai/cli/projects.md) explains the project the commands operate on.

```bash theme={null}
simple --help
simple <command> --help
```

This page lists the commands most projects use. `--help` on any command shows every flag, including the ones left out here. Commands print one line per result, or the raw API response with `--json` where it is offered; a failure prints `simple: <message>` and exits with code `1`.

## Authentication

### `simple login`

Signs in through your browser with your dashboard account. When you belong to more than one organization, the CLI asks which one to use, and remembers the choice.

| Flag | What it does |
| - | - |
| `--no-browser` | Print the sign-in URL instead of opening a browser, for a remote shell. |
| `--trust-api-host` | Sign in to an API host, given with `--api-url <url>`, that Simple does not operate. Signing in sends that host your session, so never pass this for a host you only know from a project someone handed you. |

### `simple whoami`

Prints who you are signed in as and which organization the session is on.

### `simple logout`

Signs out and removes the saved credentials. `--all` signs out every saved sign-in.

## Agent Projects

Commands for an existing project work on the current directory; pass `--directory <path>` to point at another one. `simple init` takes its target as the positional `[directory]` argument instead.

### `simple init [directory]`

Creates an agent project: a `package.json`, `tsconfig.json`, a starter `agent.ts`, and an empty `simple.lock.json`. Defaults to the current directory. Run `pnpm install` in it afterwards.

### `simple pull <agent-uuid>`

Pulls one production branch of an agent, with the exact Action versions it uses, into code. The UUID is on the agent's page in the dashboard.

| Flag | What it does |
| - | - |
| `--branch <name-or-uuid>` | The branch to pull. Without it, the most recently updated branch. |
| `--format source\|snapshot` | `source` (default) writes `defineAgent(...)` authoring code. `snapshot` writes the lossless `defineAgentSnapshot(...)` form, which pull also falls back to when a field cannot round-trip. |
| `--force` | Replace source and referenced files you changed locally. Without it, pull refuses to overwrite them. |

### `simple typecheck`

Typechecks and compiles the project, including the handlers under `actions/`. Uses the package manager named in the project's `package.json`, pnpm by default.

### `simple diff`

Lists the agent and Action changes between your source and `simple.lock.json`. Nothing is sent to production.

### `simple publish`

Validates the project on the server, creates or revises the Actions that changed, then creates one agent commit pinned to those versions. Refuses if the branch or an Action changed in production since your last pull.

| Flag | What it does |
| - | - |
| `--label <label>` | The commit label shown in the dashboard. Defaults to `Published from Simple CLI`. |

### `simple actions upgrade`

Accepts the newest production versions of the Actions already in the lock file. See [Validate and publish](https://docs.usesimple.ai/cli/projects.md#validate-and-publish) for how this interacts with `defineAgent(...)` source.

## Organization Resources

Tags, analyzers, scorecards, scorecard metrics, and post-call workflows belong to the organization, and an agent references them by UUID. Each family has `list`, which prints one line per item starting with its UUID, and `create`, which prints the new item's name and UUID:

```bash theme={null}
simple tags list
simple analyzers list
simple scorecards list
simple scorecards metrics list
simple post-call-workflows list
```

| Flag | Applies to | What it does |
| - | - | - |
| `--json` | `list` and `create` | Print JSON instead of one line per item: the full API response for `list`, the created item for `create`. |
| `--file <path>` | `create` | Read the definition from a JSON file, or from stdin with `-`. Flags given alongside override fields in the file. Required for `post-call-workflows create`. |

The most used `create` flags:

| Command | Flags |
| - | - |
| `tags create` | `--name`, `--description`, `--color`, `--always-enabled` |
| `analyzers create` | `--title`, `--prompt`, `--output string\|number\|boolean`, `--output-enum a,b,c`, `--agent <uuid>` (repeatable), `--always-enabled` |
| `scorecards create` | `--name`, `--inactive` |
| `scorecards metrics create` | `--name`, `--description`, `--criteria`, `--expect-false`, `--auto-fail` |
| `post-call-workflows create` | `--file`, `--name`, `--agent <uuid>`, `--branch`, `--enabled` |

Definition files and worked examples for each resource are on [Agents as code](https://docs.usesimple.ai/sdk/agents-as-code.md#organization-resources).

## Updating

### `simple update [version]`

Updates the CLI to the latest release, or to the version or tag you name, using the package manager that installed it globally. `--dry-run` shows what it detected and the command it would run, without installing. If the CLI is a project dependency rather than a global install, update it with that project's package manager instead.

```bash theme={null}
simple update
simple update 0.12.1
simple update --dry-run
```


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