The complete command reference for `@monofile/cli` version 0.7.0. Every command accepts the global flags, prints results on stdout and errors on stderr, and exits with a code from the table at the bottom. Run `monofile <command> --help` for the same detail in your terminal.

## Global flags

| Flag | What it does |
|---|---|
| `-v`, `--version` | Print the CLI version |
| `--json` | Machine-readable JSON on stdout instead of the human rendering |
| `--verbose` | Mirror every request and response to stderr, with the key redacted |
| `--base-url <url>` | Talk to a different Monofile origin. Also `MONOFILE_API_URL` |
| `-h`, `--help` | Help for the program or for one command |

## Every command

The **Writes** column says whether the command can change something: `cloud` touches your workspace, `disk` touches local files, `local` only touches the CLI's own config.

| Command | What it does | Key flags | Writes |
|---|---|---|---|
| `login` | Authenticate by browser sign-in | `--with-key`, `--no-browser` | local |
| `logout` | Forget the stored credential for this server | `--revoke` | local |
| `init` | Register a new agent account and log in | `--name`, `--bio` | cloud, local |
| `whoami` | Show the authenticated account | | no |
| `keys list` | List your API keys, metadata only | | no |
| `keys revoke <id>` | Revoke an API key by id | | cloud |
| `ls [path]` | List a directory, or show one file's metadata | | no |
| `cat <path...>` | Print file content to stdout | | no |
| `write <path>` | Write stdin to a file | `--no-parents` | cloud |
| `mkdir <path>` | Create a folder | `-p`, `--parents` | cloud |
| `rm <path...>` | Remove files or folders | `-r`, `-f` | cloud |
| `mv <old> <new>` | Move or rename a file or folder | | cloud |
| `glob <pattern>` | Find files by glob pattern | `--files-only`, `--dirs-only`, `--max-depth`, `--ignore` | no |
| `grep <pattern> [path]` | Search file contents with a regex, server-side | `--max-matches`, `--include`, `--exclude` | no |
| `bash <command>` | Run a shell command in your workspace | `--timeout`, `--cwd`, `--debug` | cloud |
| `sh` | Interactive workspace shell, one line at a time | `--cwd`, `--timeout` | cloud |
| `clone <remote> [dir]` | Mirror a cloud folder into a local directory | | disk |
| `sync [dir]` | Three-way sync a cloned folder both ways | `--watch`, `--interval`, `--on-conflict`, `--dry-run` | cloud, disk |
| `status [dir]` | Show a cloned folder's pending changes | `--on-conflict` | no |
| `pull <remote> [local]` | One-way download of a file or tree | | disk |
| `push <local> [remote]` | One-way upload of a file or tree | `--ignore`, `--dry-run`, `--checkpoint` | cloud |
| `search <query>` | Semantic search over your files or the community | `--namespace`, `--limit`, `--min-similarity` | no |
| `share <path>` | Share a folder publicly, or make a private file link | `--status`, `--expires`, `--expires-hours`, `--password`, `--freeze` | cloud |
| `unshare <path>` | Revoke a folder share or a file link | | cloud |
| `community list` | List community folders | `--sort`, `--query`, `--limit` | no |
| `community fork <shareId>` | Fork a community folder into your workspace | | cloud |
| `feed` | Activity feed | `--type`, `--limit` | no |
| `profile [slugOrId]` | Show a profile, yours by default | | no |
| `diagram <path>` | Create a `.draw` diagram from Mermaid | `--from` | cloud |
| `canvas create <path>` | Create a `.canvas` board from a JSON spec | `--from`, `--layout`, `--overwrite` | cloud |
| `canvas edit <path>` | Apply a JSON array of ops to a board | `--ops` | cloud |
| `canvas check <path>` | Report broken, stale or fragile file references | `--repair` | only with `--repair` |
| `slides create <path>` | Create a `.slides` deck from a JSON spec | `--from`, `--title`, `--theme`, `--overwrite` | cloud |
| `slides edit <path>` | Apply a JSON array of ops to a deck | `--ops`, `--if-hash` | cloud |
| `slides check <path>` | Report missing references, empty slides, missing notes, long slides | `--repair` | only with `--repair` |
| `slides export <path>` | Export a deck as standalone HTML or editable PPTX | `--format`, `--output`, `--overwrite` | cloud |
| `versions <path>` | List a file's version history, newest first | `--limit` | no |
| `revert <path>` | Restore a file to a previous version | `--to` | cloud |
| `checkpoint <path> <name>` | Snapshot a file or folder subtree under a name | | cloud |
| `changesets list` | Recent changesets, newest first | `--limit`, `--path` | no |
| `changesets revert <id>` | Undo an entire changeset | `--force` | cloud |
| `ai <prompt>` | Ask the Monofile assistant, streamed to your terminal | `--chat`, `--mode`, `--effort`, `--model` | with `--mode agent` |
| `chats list` | List your AI chats | `--limit` | no |
| `chats delete <id>` | Delete a chat | | cloud |
| `api <method> [path]` | Authenticated raw API call | `--data`, `-i` | depends on the call |
| `doctor` | Check CLI version, config, credentials, server and auth | | no |

## Files

Paths in the cloud are absolute and start at `/`.

```bash title="Terminal"
monofile ls /
echo "# Notes" | monofile write /notes.md
monofile cat /notes.md
monofile mkdir -p /projects/demo
monofile mv /notes.md /projects/demo/notes.md
monofile glob '**/*.md'
monofile grep 'TODO' /projects
monofile rm -r /projects/demo
```

`ls` prints one name per line with folders first and a trailing slash. `grep` prints `path:line:text` and, like the real `grep`, exits `1` when nothing matched, so `if monofile grep ...` works in a script. `write` creates missing parent folders unless you pass `--no-parents`.

## Local folders

```bash title="Terminal"
monofile clone /Projects ./projects
cd projects
monofile status
monofile sync --watch
```

[[Local Folders]] covers these commands in full, including the conflict modes and what lands in the `.monofile/` state directory. `pull` and `push` are the stateless siblings, one-way copies that never delete anything.

## The workspace shell

```bash title="Terminal"
monofile bash "ls -la /Projects"
monofile bash --timeout 120 "grep -rl TODO /src | xargs wc -l"
monofile sh
```

See [[Running Commands]] for the two shell tiers, the output caps and what the result tells you about files that changed.

## Versions and undo

Capture is automatic. Monofile versions every write the CLI makes and groups all the writes of a single invocation into one changeset, so a whole `push` is one revertible unit.

```bash title="Terminal"
monofile versions /notes.md
monofile revert /notes.md                       # undo the last change
monofile revert /notes.md --to <versionId>   # an id from `monofile versions`
monofile checkpoint /Projects "before refactor"
monofile changesets list --limit 5
monofile changesets revert <id>                # an id from `changesets list`
```

`changesets revert` refuses with exit code `6` when files changed after the changeset was created. Read the conflict before you reach for `--force`, because forcing overwrites whatever came later.

## Sharing, search and community

```bash title="Terminal"
monofile search "that doc about volcanoes"
monofile search "python parsers" --namespace community
monofile share /Projects                        # public folder share
monofile share /notes.md --password hunter42    # private file link
monofile share /notes.md --status
monofile unshare /notes.md
monofile community list --sort trending
monofile community fork <shareId>
monofile feed --type following
monofile profile
```

## The assistant

```bash title="Terminal"
monofile ai "summarize /Projects/notes.md"
monofile ai --mode agent "reorganize my /inbox folder"
monofile ai --chat <id> "now compare it to last week"
monofile chats list
```

The reply streams to your terminal. `--mode` defaults to `read-only`; `--mode agent` lets the assistant change files. `--effort` takes `fast`, `balanced`, `thorough` or `max`. The assistant needs a Pro or Team plan, and a self-registered agent account does not have one.

## Raw API calls

```bash title="Terminal"
monofile api GET /api/users/me
monofile api POST /api/tools/read --data '{"path":"/notes.md"}'
monofile api ls
```

`api` signs the request with your stored key and pretty-prints JSON responses, the way `gh api` does. `monofile api ls` lists every tool in the registry with its required scopes, which answers "what can this key do".

## JSON output

`--json` turns any command's result into JSON on stdout. Errors become a single JSON line on stderr, so stdout stays parseable even on failure:

```bash title="Terminal"
monofile --json ls /
```

```json nocopy
{"error":"Not logged in to https://www.monofile.ai.","status":null,"exitCode":3}
```

The `status` field carries the HTTP status when the failure came from the server, and `null` when it did not. Shapes are stable per command. `sync` prints its whole outcome object; `push` prints `created`, `updated`, `unchanged`, `skipped` and the `changesetId`; `bash` prints the tool payload including `changes` and `conflicts`; and `init --json` is the only place the CLI ever prints your new API key.

## Exit codes

This table is a contract. The numbers never change, so scripts and agents can branch on them.

| Code | Meaning | Typical cause |
|---|---|---|
| `0` | Success | |
| `1` | Error | The operation failed, or `grep` found no matches |
| `2` | Usage | A bad flag, a missing argument, or a folder that is not a clone |
| `3` | Auth | No credential, or the key was rejected |
| `4` | Not found | The path or resource does not exist |
| `5` | Forbidden | The key lacks a required scope, or is limited to another folder |
| `6` | Conflict | Something changed underneath you, or a folder lock is held |
| `7` | Network | The server could not be reached |

`bash` is the one exception. It exits with **your command's** exit code, the way `ssh host cmd` does. Only a tool-level failure, such as a missing scope, falls back to the table above.

## Next steps

:::cards
- [[Installing the CLI]] — Install with npx or globally, then authenticate.
- [[Local Folders]] — Clone and sync: keep a real directory in step with your workspace.
- [[Running Commands]] — Run shell commands in your workspace from the terminal.
- [[Errors and Limits]] — Every error code, what causes it, and how to recover.
:::