CLI reference
The merget command-line tool exposes the same repository operations as the
app — and it's how your coding agent drives Merget (see Your agent and Merget). It ships inside the app: each
time the app starts, it makes the bundled merget binary available at ~/.merget/bin/ so your shell can find it. There's no separate CLI install —
the CLI is part of the app, and if you delete the app, the CLI stops working
with it. You can run it from any terminal, including
the app's built-in terminals.
Terminology note: the CLI calls a step a subprompt — same object,
older name. Everywhere this guide says "step," merget output will say
"subprompt." See the glossary.
Every command supports --color <auto|always|never>; merget --version prints
the version. Run merget <command> --help for full options.
Getting set up
| Command | What it does |
|---|
merget login | Sign in to a Merget server. Methods: --method oauth (browser; --provider github\|google), password, ssh, or api-key. Add --signup to create an account. |
merget init | Initialize a Merget repo in the current directory. --repo overrides the name, --namespace the owner. Also installs agent plugins for detected agents. |
merget plugins install\|list\|remove | Manage the committing plugins in your coding agents (Claude Code, Codex, Cursor, GitHub Copilot). |
merget github connect\|status\|disconnect | Link or unlink your GitHub account (used for GitHub imports). |
Committing and history
| Command | What it does |
|---|
merget status | Current HEAD state (the four states) and whether the working tree is clean. --json for machine-readable output. |
merget commit -m "<message>" | Commit the working tree as a step, HEAD-aware. -a "Name <email>" overrides the author. |
merget log | History of goals, prompts, and steps. Scope with log goal <name> / log prompt <name>; widen with --all, --all-goals, --all-prompts, --subprompts; --json; -n <limit> (default 20). |
merget goal create\|list\|resolve | Manage goals. resolve settles a concurrent metadata conflict on a goal. |
merget prompt create\|list\|resolve | Manage prompts. |
merget recontextualize | Summarize recent history into a portable handoff brief for another agent or tool. Aliases: recontext, handoff. --full includes untruncated transcripts; --json; -n <limit>. |
Inspecting
| Command | What it does |
|---|
merget diff [FROM] [TO] [-- <paths>] | Diff between revisions (defaults: HEAD → working tree). --stat, --shortstat, --name-only, --name-status, -U <n> context lines, --diff-algorithm histogram\|myers\|myers-minimal. |
merget blame <file> | Line-level blame: which step (and therefore which prompt) wrote each line. --from <revision>, --json. |
merget show <object> | Show any object's contents (step, goal, prompt, transcript) by ID. --json. |
merget help [topic] | Built-in topic help — e.g. merget help revisions explains how revision strings resolve. |
Moving through history
| Command | What it does |
|---|
merget checkout <target> | Check out a revision — a goal, prompt, bookmark, or step prefix. Refuses if tracked files have uncommitted changes. |
merget bookmark create <name> [target] | Create a bookmark (fails if it exists; target defaults to HEAD). |
merget bookmark set <name> [target] | Create or move a bookmark. |
merget bookmark list / delete <name> | List or delete bookmarks. |
Merging
| Command | What it does |
|---|
merget merge <target> | Begin a three-way merge against a goal, prompt, bookmark, or step prefix (shortcut for merge start). |
merget merge status | Show the in-progress merge's heads, base, and unresolved paths. |
merget merge finalize | Build the merge step, advance refs, and clean up — after you've resolved conflicts. |
merget merge abort | Discard the in-progress merge safely. |
The full flow, including the GUI path: Merging goals.
Sharing and syncing
| Command | What it does |
|---|
merget repo create | Create a repository on the server. |
merget import git | Link the repo in the current directory to the server: register it, import any local .git history, and snapshot uncommitted work as a step. Idempotent — safe to rerun anytime. --no-import / --no-snapshot skip those stages; --name / --namespace override the defaults. |
merget import git --url <url> | Clone a remote Git repository (GitHub, GitLab, …) and enrich its history into a new Merget repo. --private makes the new repo private. |
merget remote add\|list\|remove | Manage remotes. |
merget push [remote] / fetch [remote] | Push or fetch refs and objects (default remote: origin). |
merget pull [remote] | Fetch and integrate; HEAD fast-forwards on a clean chain. --all pulls every remote and reconciles. |
merget clone <namespace/repo> [dir] | Clone a remote repository. |
merget collab add\|remove\|list | Manage a repo's collaborators. |
Maintenance
| Command | What it does |
|---|
merget gc | Garbage-collect: prune unreachable objects and pack the store. --dry-run, --grace-days <n> (default 14), --no-grace-period (unsafe with concurrent writers), --no-pack. |
Under the hood: revisions and plumbing
Most commands that take a revision (checkout, diff, blame, merge, bookmark) accept a goal name, prompt name, bookmark name, step-ID prefix, or HEAD/@ — merget help revisions documents the resolution rules. A few
low-level plumbing commands also exist (subprompt create, transcript store, hash-object, cat-file) for scripts and agents that manipulate objects
directly; everyday use never needs them.
Next: Supported agents · Related: Your agent and Merget · Terminals · The history model
