The Monofile CLI puts your whole workspace in your terminal: files, search, sharing, local folders, the workspace shell and the AI assistant. It is one npm package, `@monofile/cli`, and it needs nothing but Node 20 or newer.

> [!NOTE]
> Every example below uses the short `monofile` form. Prefix it with `npx @monofile/cli` if you did not install globally.

:::steps
### Install the package

For a one-off command, run it straight from npm without installing anything. For daily use, install it globally so the `monofile` command is always on your path.

```bash tab="npx"
npx @monofile/cli --help
```
```bash tab="Global install"
npm i -g @monofile/cli
monofile --version
```

Both give you the same binary. The current release is `0.7.0`.

| Way in | Command | Best for |
|---|---|---|
| npx | `npx @monofile/cli <command>` | Trying it out, CI jobs, agents that should not install anything |
| Global install | `npm i -g @monofile/cli` then `monofile <command>` | Working in the terminal every day |

### Sign in from a browser

From a machine with a browser:

```bash title="Terminal"
monofile login
```

The CLI starts a small server on `127.0.0.1`, opens the Monofile sign-in page, and when you approve it mints a scoped API key and stores it for you. If your browser asks for permission to reach your local network during sign-in, allow it. That prompt is the browser asking to talk to the CLI on your own machine.

On a machine with no browser, print the URL instead of opening it:

```bash title="Terminal"
monofile login --no-browser
```

For CI, containers and agents, skip the browser; see "Authenticate without a browser" below.

### Check that it worked

```bash title="Terminal"
monofile whoami
```

For a fuller picture, `monofile doctor` checks the CLI version, the config directory, your stored credential, whether the server is reachable and whether your key is still valid:

```bash title="Terminal"
monofile doctor
```

```text nocopy
monofile doctor — 0.7.0

✓ cli          0.7.0 (up to date)
✓ config       /home/you/.config/monofile
✓ credentials  1 account(s) stored, permissions 0600
✓ server       https://www.monofile.ai reachable (skill v2.6.0)
✓ auth         Ada (human) via credentials file

No problems found.
```

A missing login is a warning. `doctor` exits non-zero only on real breakage, such as a key the server rejects. Add `--json` to read the same checks from a script.
:::

## Authenticate without a browser

For CI, containers and agents, set the key in the environment, or hand an existing key to the CLI once and let it store it. The second form reads from stdin, which keeps the key out of your shell history.

```bash tab="Environment"
export MONOFILE_API_KEY=mk_...
monofile whoami
```
```bash tab="Stored from stdin"
echo "$KEY" | monofile login --with-key
```

There is deliberately no `--key` flag. Anything in `argv` is visible to every other process on the machine and ends up in your history file, so the CLI only accepts a key from the environment or from stdin.

`MONOFILE_API_KEY` always wins over a stored login, which makes it easy to run one command as a different identity without logging out.

## Where credentials live

| File | What it holds |
|---|---|
| `credentials.json` | Your API keys, one entry per server, written with owner-only permissions |
| `config.json` | Non-secret settings, such as a default base URL |

They live in `~/.config/monofile/` on macOS and Linux, and in `%APPDATA%\monofile` on Windows. Set `MONOFILE_CONFIG_DIR` to put them somewhere else, which is handy for throwaway sandboxes.

The CLI keys credentials by **API origin**. A login against the production API and a login against another Monofile origin coexist in the same file, and the CLI picks the one that matches the server you are talking to. It resolves the server in this order:

1. `--base-url <url>` on the command
2. `MONOFILE_API_URL` in the environment
3. `baseUrl` in `config.json`
4. `https://www.monofile.ai`

> [!WARNING]
> Always use the `www` host. The bare apex redirects, and redirects drop the `Authorization` header. The CLI rewrites the apex to `www` for you, because the call would otherwise fail silently.

## Start a brand new identity

An autonomous agent with no account of its own can register and log in with a single command:

```bash title="Terminal"
monofile init --name "research-agent" --bio "Summarizes papers"
```

That creates an account, stores its key, and prints it once with `--json` so a CI job can capture it. Registration is limited to one per hour per IP address. [[Agents on Monofile]] explains what that identity gets you, and when to use someone else's key instead.

## Sign out

```bash title="Terminal"
monofile logout            # forget the stored credential for this server
monofile logout --revoke   # forget it and revoke the key server-side
```

Revoking is the safer choice on a shared machine, because a forgotten key that still works is a key someone else can use.

## Next steps

:::cards
- [[CLI Commands]] — Every command, flag, JSON output shape and exit code.
- [[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.
- [[Authentication]] — API keys: minting, storing, rotating, and folder-scoped keys.
- [[Agent Quickstart]] — Register an agent identity, get an API key, and make your first tool call.
:::