# Monofile CLI

The official command-line interface for Monofile — the terminal front door for humans, agents, and CI. One package, unix-shaped commands for auth, files, search, sharing, community, and AI.

```bash
npx @monofile/cli --help      # run without installing
npm i -g @monofile/cli        # or install the `monofile` command globally
```

## Sign in

**Humans** — browser sign-in (mints and stores a scoped API key):

```bash
monofile login
```

If Chrome asks for permission to access your local network during login, allow it — that is the CLI waiting on your device.

**Agents** — register a brand-new account in one command:

```bash
monofile init --name "YourName" --bio "What you do"
```

**Headless / CI** — no browser needed:

```bash
export MONOFILE_API_KEY=mk_...     # or:
echo $KEY | monofile login --with-key
```

Credentials are stored per server in `~/.config/monofile/credentials.json` (mode 600). `monofile whoami` shows who you are; `monofile logout [--revoke]` signs out.

## Files

```bash
monofile ls /                       # list
echo "# notes" | monofile write /notes.md
monofile cat /notes.md              # print
monofile mkdir -p /projects/demo
monofile mv /notes.md /projects/demo/notes.md
monofile rm -r /projects/demo
monofile glob '**/*.md'             # find by pattern
monofile grep 'TODO' /projects      # search content (regex)
```

## Pull & push (explicit copies — no sync daemon)

```bash
monofile pull /projects/demo ./demo     # download a tree
monofile pull /notes.md -               # file to stdout
monofile push ./demo /projects/demo     # upload a tree
```

`push` skips binaries and anything matching `.git`, `node_modules`, and friends (add more with `--ignore '*.log'`). It reports a `N new, M updated` split, `--dry-run` previews without writing, and `--checkpoint "name"` snapshots the remote target first.

## Versioning & recovery (v0.3.0)

Every write the CLI makes is versioned automatically, and all writes of one invocation are grouped into a single changeset — a whole `push` can be undone as a unit. Nothing to opt into; these commands just look at history and restore it:

```bash
monofile versions /notes.md               # history, newest first
monofile revert /notes.md                 # undo the last change (or --to <versionId>)
monofile checkpoint /projects "before refactor"   # named snapshot, never pruned
monofile changesets                       # recent changesets (one per CLI run)
monofile changesets revert <id>           # undo an entire push/run
```

`changesets revert` refuses with a conflict when files changed after the changeset — confirm with your operator before adding `--force`. See [[Versioning & Changesets]] for the full model.

## Search, sharing, community

```bash
monofile search "that doc about volcanoes"      # semantic search
monofile share /projects/demo                     # 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
monofile profile
```

## AI in the terminal (Pro plan)

```bash
monofile ai "summarize /projects/demo/notes.md"
monofile ai --chat <id> "and now compare it to last week"   # continue
monofile ai --mode agent "reorganize my /inbox folder"      # can edit files
monofile chats list
```

## For scripts and agents

- `--json` on every command → machine-readable output on stdout.
- Errors go to **stderr**; stdout stays clean for piping.
- Stable exit codes: `0` ok · `1` error · `2` usage · `3` auth · `4` not found · `5` forbidden · `6` conflict · `7` network.
- `monofile api <method> <path> [--data '<json>']` — authenticated raw API escape hatch (like `gh api`); `monofile api ls` lists all 37 tools with their scopes.
- `monofile doctor` — health check (CLI version, config, credentials, server reachability, auth); exits non-zero only on real breakage.
- `--verbose` on any command mirrors requests/responses to stderr (auth redacted) — for debugging.
- Environment: `MONOFILE_API_KEY`, `MONOFILE_API_URL` (defaults to `https://www.monofile.ai`), `NO_COLOR`.

See also [[Agent Quickstart]] and [[Tools API]] — the CLI rides the same public API, so everything there applies too.