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

# Install and Use the Simple AI CLI

> Install the simple CLI, sign in with your Simple AI account, and pull, typecheck, diff, and publish your first agent from a TypeScript project.

The `simple` CLI (`@simple-ai-lab/cli`) moves agents between production and a TypeScript repository. You define an agent in code with the [SDK](https://docs.usesimple.ai/sdk/agents-as-code.md); the CLI pulls it from production, shows what you changed, and publishes it back.

## Install

```bash theme={null}
pnpm add -g @simple-ai-lab/cli
```

`npm install -g`, `yarn global add`, and `bun add -g` work too. pnpm 10 may warn that it ignored esbuild's build script; the CLI works without it, so there is nothing to approve.

The CLI needs Node.js 20 or later and a Simple AI account that belongs to at least one organization. Agent projects use pnpm to install dependencies and typecheck; `simple typecheck` runs npm, yarn, or bun instead when the project's `package.json` names one of them as its `packageManager`.

## Authentication

```bash theme={null}
simple login
simple whoami
```

`login` opens your browser and signs you in with the same account you use for the dashboard. When you belong to more than one organization, it asks which one to use. The session is saved, so you sign in once and every later command uses it. `whoami` confirms who you are signed in as and which organization the session is on. When you are done, `simple logout` ends the session and removes the saved credentials.

The CLI never takes an API key. Every command runs with your own permissions.

## Start a Project

There are two ways to start. For a new agent, `simple init` creates a starter project:

```bash theme={null}
simple init my-agent
cd my-agent
pnpm install
```

For an agent that already exists in production, `simple pull` writes it into a new directory. The agent's UUID is shown on its page in the dashboard:

```bash theme={null}
mkdir my-agent && cd my-agent
simple pull <agent-uuid> --branch main
pnpm install
```

Either way the project has `agent.ts`, a `package.json` and `tsconfig.json`, and `simple.lock.json`, which the CLI uses to track what the project was last synchronized with. A pulled agent also has its Code Action handlers under `actions/` and its prompts under `prompts/`. Check all of it into source control except `node_modules`.

## Edit, Diff, Publish

Edit `agent.ts`, the handlers, or the prompts, then run the three commands that make up the loop:

```bash theme={null}
simple typecheck   # compile the project, handlers included
simple diff        # show what changed since the last pull or publish
simple publish --label "Improve account lookup"
```

Publish validates the whole project on the server first, and refuses to overwrite changes made in production since your last pull.

## Next Steps

* [Agent projects](https://docs.usesimple.ai/cli/projects.md): what `pull` writes, what the lock file records, and how `publish` keeps code and production in step.
* [CLI reference](https://docs.usesimple.ai/cli/reference.md): every command you will use, with its flags.
* [Agents as code](https://docs.usesimple.ai/sdk/agents-as-code.md): the `defineAgent` API, Actions, and organization resources.


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