--- title: "Cork CLI (corkcli): the cork command · Cork" description: "Cork CLI is the cork command that npx corkcli installs: it sets up Claude Code, Codex, Cursor and Hermes. Reference for cork status, login, update, message, land, uninstall and every other command, with their flags." canonical: "https://corkcli.com/docs/cli" last_updated: "2026-11-13" --- # Cork CLI (corkcli): the cork command Cork CLI is the `cork` command that `npx corkcli` installs: one program, in `~/.cork/bin` and on your PATH, that sets up Claude Code, Codex, Cursor and Hermes so the agents on a codebase see each other's work. It is both the agents' hooks and, on a free, local machine, the local server. These are the commands you run yourself. ## Install ``` curl -fsSL https://corkcli.com/install.sh | sh ``` Or `npx corkcli`. If `cork` is not on your PATH yet in the current shell, run it by its full path, `~/.cork/bin/cork`. Running `cork` with no command prints the short list. Cork was called Collide until November 2026. On a machine that installed it then, the program stays in `~/.collide/bin` with a `cork` next to the old `collide`, so both names run the same commands, and `~/.collide` stays its data folder. A repo's `.collide/config.json` and `COLLIDE_` environment variables are still read when there is no `.cork` or `CORK_` one. ## Commands ### `cork status` What Cork runs on this machine and whether it is running: on a free, local machine, the local server's address, the data folder, and what Cork did in the last day and since install; on a machine that works with a team, the server it reports to. A machine signed in to an account also gets one line from the [status page](https://corkcli.com/status) (from hooks v84): "Cork service: operational", or what is not; nothing when the page cannot be read. ### `cork status --mine [--session ID]` What this agent session wrote that is not committed yet. ### `cork login [--server URL]` Links this machine to your Cork account through a browser sign-in, from any folder. The credential is kept in `~/.cork/credentials.json`. The machine moves to Cork's servers and syncs its history, on Free too: your agents on every machine you sign in on see each other's work, and Free is metered in agent hours, not machines. `--server` signs in to another Cork server (default `https://mcp.corkcli.com`). ### `cork update` Checks for a new version of the `cork` program now and puts it in place, then says in one line what happened: `cork is up to date (v100)`, or `Updated cork v97 → v100` (restart open agent sessions to use it), or why it could not. Cork also updates itself within the hour; this skips that wait, and the hold a `cork rollback` leaves. ### `cork rollback` Puts back the version the last update replaced, which is kept beside the program. Updates then wait for a release newer than the one you left (or for `cork update`); run it again to switch back. ### `cork upgrade` Units for the machine's workspace (100 agent hours a month each, pooled across it, $20 a unit): signs in first if the machine is not linked yet, then opens the workspace's billing page. The units cover every machine signed in to the workspace as soon as they are paid for. For a new version of the program itself, use `cork update`. ### `cork add` Run inside a repository on a signed-in team machine: shares it with your team's workspace. Only a repository with a remote on GitHub or another git host can be added. ### `cork message [--to AGENT | --about path.py::symbol] "what to tell them"` Tells the other agents in this repository something. With neither flag it goes to every agent at work in the repo right now; `--to` sends it to one agent; `--about` sends it to whoever is working on that code. Run it inside the repository. ### `cork ack ...` Marks messages as handled so they stop coming back. The ids are the ones shown in brackets when a message arrives. ### `cork commit --mine [-m MSG] [--dry-run] [--include-mixed] [--session ID]` Stages, and with `-m` commits, only the lines this session wrote; other sessions' and unattributed lines stay as they are. `--dry-run` (or `-n`) shows what it would take. `--include-mixed` also takes changes where this session's lines are mixed with another's. `--session` names the session when it cannot be told. ### `cork land [--test CMD]` Lands this branch's commits: takes the repo's push turn, rebases onto what teammates pushed, runs the tests when anything came in, and pushes. In Claude Code an agent's plain `git push` becomes this. In [trunk mode](#trunk-mode), on a branch of its own, it lands that branch into the trunk instead. ### `cork trunk on [--branch dev] [--promote-to main] [--policy auto|pr|ask] | off | status` Switches [trunk mode](#trunk-mode) for the repo you are in, for every machine and teammate. `--branch` is the trunk (default: `dev` when origin has it, else the default branch; one origin lacks is made from the promotion target). `--promote-to` defaults to `main`. `--policy` says how a finished branch lands: `auto` (default) lands it, `pr` opens a pull request into the trunk, `ask` lists it for you. In a team, the workspace's owner switches it. ### `cork branches [land | delete | land-clean]` The branches agents made (open, landed, abandoned, conflicted), whose, how old, and how far ahead of the trunk, then the branches from before trunk mode. `land` lands one now, whatever the policy; `delete` deletes one whose work is all on the trunk (never one with unlanded commits); `land-clean` lands every branch that merges cleanly and deletes the ones already on the trunk, and leaves the rest listed. ### `cork promote` Opens, or brings up to date, the one pull request from the trunk to the promotion target, listing what landed since the last promotion. With the GitHub CLI (`gh`) it opens it; without, it prints the address that does. Cork never merges it. ### `cork wake on|off|status` `on`: when a teammate's agent messages you and none of your agents is running in that repo, this machine starts one (Claude Code, else Codex, found on your PATH) in a new worktree to weigh the message, answer it and leave any work on a branch. Needs the machine signed in to a team. `off` stops it; `status` says whether it is on. ### `cork badge on|off|status` Whether pull requests your agents open end with Cork's badge, `[![coordinated by cork](https://corkcli.com/badge.svg)](https://corkcli.com)`. In Claude Code and Codex the hooks add it to the description right after `gh pr create`, with your own `gh`; in Cursor and Hermes the agent is asked to add it. Once per pull request: remove it and it stays removed. It is on from install, which says so once. `off` stops it on this machine (kept in `~/.cork/machine.json`); `CORK_PR_BADGE=0` in the environment does the same wherever it is set. [The badge](https://corkcli.com/docs#badge) is also yours to put in a README. ### `cork statusline on|off` `on`: Cork in Claude Code's status line, as `cork · 3 agents here · 2 catches today`: the agent sessions at work in this repo on this machine, and the writes Cork stopped today because they would have collided. It reads what the hooks already recorded, so it never waits on the network. It is added to `~/.claude/settings.json` only when no status line is set there; one of your own is never replaced. `off` takes out only Cork's. ### `cork migrate` Run inside a repository: removes its old per-repo Cork setup (hook files under `.collide/`) and stages the change for you to commit. Cork must already be installed on the machine, since the machine's hooks take its place. ### `cork uninstall` Takes Cork's hooks and MCP entry out of your agent tools and turns wake off. Your local data stays in `~/.cork`. Restart open agent sessions: they keep the hooks they started with. ### `cork pre-commit` The git pre-commit gate: blocks a commit whose staged files land on a certain in-flight collision. Override a false positive with `git commit --no-verify`. To use it in a repository: ``` printf '#!/bin/sh\nexec "$HOME/.cork/bin/cork" pre-commit\n' > .git/hooks/pre-commit chmod +x .git/hooks/pre-commit ``` ### `cork mcp` Cork's MCP tools over stdio. The install registers this as the `cork` MCP server in your agent tools; you do not run it yourself. ### `cork --version` The program's version and the hook artifact version. ## Trunk mode Agents make a branch for every feature and leave the merging to you, so no one branch has everything. With `cork trunk on` (or the toggle in the repo's settings on the dashboard), a repo's agents are told at session start, in Claude Code, Codex and Cursor alike, to work on the trunk (`dev`), commit their own lines with `cork commit --mine` and land them once the tests pass. A branch or worktree is for large or risky work only; one that does get made is reminded of once, never blocked. A branch lands into the trunk when its task is done: a subagent stopped on it with everything committed, a session ended on it with a clean tree, or the agent ran `cork land`. It is rebased onto the trunk, tested and pushed through the same push turn as every landing, a stacked branch after the one under it; then it is deleted, here and on origin, and its agent worktree removed. Uncommitted work, failing tests and anything that would need a force push never land; a conflict is left as it was, marked conflicted, and told to the owner's next session and the dashboard. Sessions on the trunk elsewhere hear at their next prompt that it moved, and a clean checkout that is only behind is fast-forwarded. Promotion stays yours: `cork promote` keeps one pull request from the trunk to `main`, and nothing ever merges into `main` by itself. It changes where work lands, never how many agents you run. ## Run by the hooks The agents' hooks run the same program as `cork report` and `cork gate`. They read the hook event on stdin; you do not need to run them. ## Questions ### What is Cork CLI? Cork CLI is the `cork` command from `corkcli`, the npm package Lithometric publishes for Cork. Cork keeps AI coding agents that work on one codebase from overwriting each other: the command installs hooks that brief each agent on the code it is about to touch and check its writes against teammates' live changes, and gives you commands such as `cork status`, `cork message` and `cork land`. ### How do I install Cork CLI? Run `npx corkcli` in any terminal with Node, Windows PowerShell included, or `curl -fsSL https://corkcli.com/install.sh | sh` on macOS and Linux. Either sets up every repo on the machine at once; `cork status` then shows what is running. If `cork` is not on your PATH yet in the current shell, run `~/.cork/bin/cork`. ### Which coding agents does Cork CLI work with? The install sets up Claude Code, Codex, Cursor and Hermes. Gemini CLI, VS Code and GitHub Copilot, Windsurf, claude.ai, ChatGPT and any other MCP client connect to the [Cork MCP server](https://corkcli.com/docs/mcp-tools.md) at `https://mcp.corkcli.com` instead. ### Is Cork CLI free? Yes. On one machine with no account, Cork is free and local: unlimited agents and repos, and the data stays on the machine. Signed in with `cork login`, Free is 10 agent hours a month per account, plus 30 bonus hours the first month; more is $20 a month per unit of 100 agent hours, pooled across the workspace. See [pricing](https://corkcli.com/pricing.md). ### How do I update or remove Cork CLI? Cork updates itself within the hour; `cork update` does it now, and `cork rollback` puts the previous version back. `cork uninstall` takes Cork's hooks and MCP entry out of your agent tools and leaves your local data in `~/.cork`. ## More - [Claude Code](https://corkcli.com/docs/claude-code.md) · [Codex](https://corkcli.com/docs/codex.md) · [Cursor](https://corkcli.com/docs/cursor.md) · [Gemini CLI](https://corkcli.com/docs/gemini-cli.md) - [Cork MCP server](https://corkcli.com/docs/mcp-tools.md): its URL and every tool it defines - [Documentation](https://corkcli.com/docs) · [Support](https://corkcli.com/support)