All fifteen commands.
Complete reference for every cow command and option.
cow create [OPTIONS] [NAME]
Create a new cow pasture (copy-on-write workspace) from a repository using APFS. Names are automatically scoped by source repository: feature-x becomes brightblur/feature-x. Omit the name and cow auto-generates brightblur/agent-1, brightblur/agent-2, and so on. Supply an explicit scope/name to override the default scope.
| Option | Description |
|---|---|
--source <PATH> | Source repository to clone (default: current directory) |
--branch <BRANCH> | Override the branch name (default: same as pasture name) |
--no-branch | Do not switch or create a branch after cloning |
--change <CHANGE> | jj change ID to edit in the new pasture (jj repos only) |
--from <REV> | jj revision to branch from — creates a new change on top rather than editing directly (jj repos only) |
-m, --message <MSG> | Set the initial jj change description immediately after creation (jj repos only) |
--dir <PATH> | Parent directory for pastures (default: ~/.cow/pastures/) |
--worktree | Create a git linked worktree instead of an APFS clone. All worktree pastures share the same .git/objects/ pack store — cross-pasture rebase works without any remote (git only) |
--no-symlink | Skip large-directory detection and always perform a full clone |
--no-clean | Skip post-clone cleanup of runtime artefacts (.pid, .sock, etc.) |
--print-path | Print only the pasture path on stdout after creation, suppressing all other output — useful for scripting and automation |
clonefile(2) directly — the same kernel syscall Time Machine uses. A 2 GB repository clones in around 130 ms wall time, with near-zero extra disk until files are modified.
cow list [OPTIONS]
List all active pastures managed by cow. Names are shown in source/pasture form. The branch column is omitted when the branch matches the pasture name. Status shows dirty (N) with a file count.
| Option | Description |
|---|---|
--source <PATH> | Filter to pastures created from this source repository |
--json | Machine-readable JSON output for scripting and MCP tools |
cow status [NAME]
Show detailed status of a pasture, including its path, source repository, branch, dirty/clean state, and a short diff summary. Defaults to the current directory if it is a cow pasture.
cow diff [NAME]
Show uncommitted changes in a pasture relative to its last commit. Passes through to git diff or jj diff as appropriate. Defaults to the current directory if inside a pasture.
cow extract [OPTIONS] <NAME>
Extract committed changes from a pasture back into the source repository. Use --patch to produce a patch file for review, or --branch to land the branch directly in the source repo so you can push a PR normally.
| Option | Description |
|---|---|
--patch <FILE> | Write a unified diff patch to this file |
--branch <NAME> | Create (or update) this branch in the source repo at pasture HEAD |
cow extract goes from pasture to source. cow sync goes the other way.
cow remove [OPTIONS] <NAME...>
Remove one or more pastures. Warns before removing pastures with uncommitted changes, and offers to push unpushed commits first. Pass multiple names to remove several pastures at once.
| Option | Description |
|---|---|
--force | Skip dirty-state warnings and remove without prompting |
-y, --yes | Skip confirmation prompts without implying a safety override — dirty warnings are still shown |
--all | Remove all pastures (can be scoped with --source) |
--source <PATH> | Scope --all to pastures from this source repository |
cow sync [SOURCE_BRANCH]
Fetch the latest commits from the source repository and rebase (or merge) the pasture onto them. Defaults to syncing with the pasture's own branch; pass a branch name to sync against a different one (e.g. cow sync main).
| Option | Description |
|---|---|
--merge | Merge instead of rebase |
--name <NAME> | Target a named pasture instead of auto-detecting from the current directory |
cow migrate [OPTIONS]
Discover existing git linked worktrees, jj secondary workspaces, and orphaned cow directories for a source repository and migrate each one into a proper cow-managed APFS clone pasture. Without --all, lists candidates and exits — nothing is modified.
| Option | Description |
|---|---|
--source <PATH> | Source repository to scan (default: current directory) |
--all | Migrate all discovered candidates without prompting |
--force | Migrate dirty candidates (those with uncommitted changes) |
--dry-run | Print what would happen without making any changes |
cow run <NAME> <CMD> [ARGS...]
Run a command inside a pasture's working directory. Automatically detects the package manager from lockfiles (pnpm-lock.yaml, yarn.lock, bun.lockb/bun.lock, package-lock.json) and injects shims so install subcommands write to the pasture-local node_modules rather than the shared source. All other subcommands pass through unchanged.
COW_PASTURE — pasture nameCOW_SOURCE — absolute path to the source repositoryCOW_PASTURE_PATH — absolute path to the pasture directory
cow materialise <NAME>
Replace symlinked dependency directories in a pasture with real APFS clonefiles. After materialisation the pasture is fully independent — packages can be added, removed, or upgraded without affecting the source or any other pasture.
node_modules, vendor, .venv, Pods, etc.) are symlinked per-package at create time to keep clone overhead near zero. Run cow materialise when you need full isolation for package management.
cow fetch-from <FROM> [OPTIONS]
Fetch all refs from another pasture into this one, enabling cross-pasture rebase without touching any remote. Useful for rebasing one agent's work on top of another's.
| Option | Description |
|---|---|
--name <NAME> | Pasture to fetch into (default: current directory) |
--force | Allow fetching from a pasture with a different source repository |
cow recreate <NAME> [OPTIONS]
Remove a pasture and immediately re-create it from the same source. Useful for getting a clean slate without having to remember the original source path.
| Option | Description |
|---|---|
--branch <BRANCH> | Override the branch checked out in the fresh clone |
--no-branch | Do not switch or create a branch (stay on source's current branch) |
cow cd <NAME>
Print the absolute path of a named pasture. Designed for shell integration rather than direct use.
cow install to set up shell integration automatically (zsh and bash supported). This adds cowcd and tab completion to your shell config.Then use
cowcd brightblur/feature-x to jump straight into a pasture. Tab completion requires jq.A shell function is required because a subprocess cannot change the working directory of its parent shell — this is a fundamental Unix constraint, and the same reason tools like
z and fzf also require shell functions for directory jumping.
cow install
Install the cowcd shell function and tab completion into your shell config (~/.zshrc for zsh, ~/.bashrc for bash). Idempotent — safe to run multiple times. Detects your shell from $SHELL.
cow mcp
Run cow as a Model Context Protocol stdio server, exposing all cow commands as MCP tools so agents can manage pastures without any human intervention: cow_create, cow_list, cow_remove, cow_status, cow_sync, cow_extract, cow_migrate, cow_materialise, cow_fetch_from, and cow_run.
~/.claude.json (global) or a project-local .mcp.json. See the MCP section on the homepage for the config snippet.
.cow.json — project config
Add a .cow.json to the root of your repository to define project-specific post-clone behaviour. Runs automatically after every cow create.