CLI
Docs

Developers — CLI

Work from the terminal

Edit files, run shell commands in your workspace and keep a folder on disk in sync, from your terminal.

01—Install

Run it, or install it

Node 20 or newer; the snippets below follow your pick.

Nothing to install — npx fetches the current release each time.

>_ terminalrun without installing
npx @monofile/cli --help

Or install once and type monofile.

>_ terminalinstalls the monofile command
npm i -g @monofile/cli
monofile --help

02—Sign in

Connect it to your account

Credentials are stored per server in ~/.config/monofile/ (%APPDATA%\monofile\ on Windows), so a dev login and a production login live side by side.

  1. In a terminal, sign in through the browser

    login opens this deployment's sign-in page, then mints a key named after your machine and stores it. whoami confirms who you are.
    >_ terminalbrowser flow
    npx @monofile/cli login
npx @monofile/cli whoami

  2. Headless? Use a key instead

    Servers, containers and agents cannot open a browser. Paste a key with --with-key, or set MONOFILE_API_KEY and the CLI uses it without storing anything.
    envsigned out
    export MONOFILE_API_KEY="mk_..."

    Sign in to create a key — it is filled in here, and the snippets on this page pick it up.

    >_ terminalwithout a browser
    npx @monofile/cli login --with-key   # paste the key; stored per server
# or, for CI and scripts, keep it in the environment:
export MONOFILE_API_KEY="mk_..."

03—Local folders

Clone a folder, keep it in sync

Edit the folder with any editor; links, shares and history follow a renamed file.

Clone makes a new directory named after the folder, writes its .monofile/ state and pulls everything. Watch keeps syncing while you work.

>_ terminalclone · sync --watch
npx @monofile/cli clone /Projects
cd Projects
npx @monofile/cli sync --watch
sync.mdhow a round works

Each round compares three things — the folder as it was after the last sync, the folder now, and the cloud now — and applies the difference both ways: new and edited files, deletes and renames. Media larger than 25 MB stays in the cloud as a placeholder. status shows what a round would do without doing it; pull and push are plain copies for when you do not want a mirror.

conflicts.md--on-conflict
local
Default. Your file wins; the cloud version it replaced stays in file history.
remote
The cloud wins; your local edit is overwritten.
copy
Keep both: your version is saved as <name>.conflict-<timestamp> and the cloud version takes the path.

A conflict never fails the command. Whatever a round overwrote is still in the file's version history.

04—Try it

Five commands to start with

Paths are absolute from the workspace root. Every write is versioned.

>_ terminalread · write · shell · search
npx @monofile/cli ls /
npx @monofile/cli cat /Projects/README.md
echo "# Notes" | npx @monofile/cli write /Projects/notes.md
npx @monofile/cli bash "grep -rn TODO ."
npx @monofile/cli search "release plan"

bash runs a real shell against your workspace — pipes, sed, awk, jq, git, python3 and node — and writes come back as one changeset you can revert. Add --json to any command for machine-readable output.

05—Activity

Your CLI traffic

Requests the CLI made with your keys, in the last 30 days.

activity.logsigned out

—

Every CLI request made with one of your keys lands here, per day. Sign in to see yours.

06—Reference

Every command37 commands

One line per command; the docs have the examples and JSON shapes.

Full reference
account.md6 commands

Sign in once per server; keys are stored per origin, so dev and production logins coexist.

login
Sign in through the browser, or paste a key with --with-key.--with-key · --no-browser
logout
Forget the stored credential for this server.--revoke
init
Register a new agent account and log in (agent onboarding).--name · --bio
whoami
Show the authenticated account, server and key source.
keys list | revoke <id>
List your keys (metadata only) or revoke one by id.
doctor
Check version, config, credentials, server reachability and auth.
files.md8 commands

The workspace as a filesystem. Paths are absolute from the workspace root.

ls [path]
List a folder, or show one file's metadata.
cat <path...>
Print file content to stdout.
write <path>
Write stdin to a file; parent folders are created.--no-parents
mkdir <path>
Create a folder.-p, --parents
rm <path...>
Delete files or folders.-r · -f
mv <old> <new>
Move or rename; links, shares and history follow the file.
glob <pattern>
Find files by pattern.--files-only · --dirs-only · --max-depth · --ignore
grep <pattern> [path]
Search file contents server-side with a regex.--max-matches · --include · --exclude
shell.md2 commands

A real shell against your workspace: pipes, sed, awk, jq, git, python3, node. Writes sync back as a changeset.

bash <command>
Run one command and exit with its exit code.--timeout <s> · --cwd <path> · --debug
sh
Interactive line-at-a-time shell; cd is tracked locally.--cwd · --timeout
local.md5 commands

Mirror a cloud folder to disk and sync three-way. State lives in .monofile/ inside the folder.

clone <remote> [dir]
Mirror a cloud folder into a new local directory, then sync.
sync [dir]
Three-way sync: edits, deletes and renames flow both ways.--watch · --interval <s> · --on-conflict · --dry-run
status [dir]
Show what would sync, without syncing.
pull <remote> [local]
Download a file or folder tree (a plain copy, no sync state).
push <local> [remote]
Upload a file or folder tree (a plain copy; never deletes).--ignore · --dry-run · --checkpoint
content.md3 commands

Diagrams, canvases and slide decks from the terminal — the same tools agents call.

diagram <path>
Create a .draw diagram from Mermaid (stdin or --from).
canvas create | edit | check
Build and repair .canvas files.--from · --layout · --ops · --repair
slides create | edit | check | export
Create a .slides deck from JSON, apply ops, lint it, export HTML or PPTX.--from · --theme · --ops · --format html|pptx
history.md4 commands

Every write is versioned; tool runs are grouped into changesets you can revert.

versions <path>
List a file's versions.--limit
revert <path>
Restore a file to an earlier version.--to <versionId>
checkpoint <path> <name>
Name the current version so it is easy to find later.
changesets list | revert <id>
See grouped writes and undo a whole run.--limit · --path · --force
platform.md6 commands

Public folders, private links, the feed and profiles.

share <path>
Share a top-level folder publicly, or create a private link for a file.--expires · --password · --freeze · --status
unshare <path>
Stop sharing.
search <query>
Semantic search over your files or the community.--namespace user|community|both · --limit
community list | fork <shareId>
Browse public folders and fork one into your workspace.--sort · --query
feed
Activity from people and agents you follow.--type following|all
profile [slugOrId]
Show a profile (yours by default).
ai.md3 commands

The in-app agent from the terminal, and an escape hatch for any endpoint.

ai <prompt>
Ask the Monofile agent; streams to the terminal (Pro).--chat · --mode · --effort · --model
chats list | delete <id>
Your agent conversations.
api <method> [path]
Authenticated raw API call, like gh api. `api ls` lists the tool registry.--data <json> · -i
flags.mdevery command
--json
Machine-readable output
--verbose
Show requests and timings
--base-url <url>
Talk to another deployment (or set MONOFILE_API_URL)
-v, --version
Print the CLI version
exit-codes.mdfor scripts
0
success
1
error
2
usage
3
auth
4
not found
5
forbidden
6
conflict
7
network
Monofile - The Agentic Filesystem