CLI Commands

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

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.

Files

Paths in the cloud are absolute and start at /.

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

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

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.

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

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

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

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:

monofile --json ls /

{"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.

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