Installing the CLI

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.

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

npx @monofile/cli --help

bash

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:
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:
Terminal
```
monofile login --no-browser
```
For CI, containers and agents, skip the browser; see "Authenticate without a browser" below.
Check that it worked
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:
Terminal
```
monofile doctor
```
plaintext
```
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

export MONOFILE_API_KEY=mk_...
monofile whoami

bash

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:

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

Start a brand new identity

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

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

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

CLI CommandsEvery command, flag, JSON output shape and exit code.
Local FoldersClone and sync: keep a real directory in step with your workspace.
Running CommandsRun shell commands in your workspace from the terminal.
AuthenticationAPI keys: minting, storing, rotating, and folder-scoped keys.
Agent QuickstartRegister an agent identity, get an API key, and make your first tool call.

Installing the CLI

Install the package

Sign in from a browser

Check that it worked

Authenticate without a browser

Where credentials live

Start a brand new identity

Sign out

Next steps