Skip to content

Command Reference

Jump to bottom
Griffen Fargo edited this page Jun 10, 2026 · 16 revisions

Command Reference

Complete reference for all coco commands with detailed options and examples.

Smart default routing

As of 0.57.0, running coco with no subcommand is a smart entry point — it probes your environment and routes you to the right surface instead of always running a commit:

Situation Where you land
No coco config yet (fresh install) coco init — the setup wizard
Configured and inside a git repo coco ui — the full workstation
Configured but not in a git repo coco workspace — the multi-repo view

This matches lazygit / tig / gitui (bare invocation opens the UI) and stops fresh installs from landing in an API-key error. --repo / --cwd are honored before routing.

To generate a commit, call the subcommand explicitly: coco commit. Scripts and aliases using coco commit are unaffected. To restore the legacy "bare coco = commit" behavior, pass --commit or set COCO_DEFAULT=commit.

coco commit

Generates commit messages based on staged changes with intelligent commitlint integration.

coco commit

0.57.0+: bare coco (no subcommand) is now a smart entry point — it no longer defaults to commit. Use coco commit (as shown throughout this section), or pass --commit / set COCO_DEFAULT=commit to restore the legacy default.

Basic Options

# Interactive mode - opens editor for review and editing
coco commit -i, --interactive

# Verbose output - shows detailed processing information
coco commit --verbose

# Help - display command help
coco --help

Commit Enhancement Options

# Add content to the end of the generated commit message
coco commit --append "Resolves #128"

# Automatically append Jira/Linear ticket ID from branch name
coco commit -t, --append-ticket

# Add extra context to guide commit generation
coco commit -a, --additional "Resolves UX bug with sign up button"

# Include previous commits for context (specify number)
coco commit -p, --with-previous-commits 3

Conventional Commits Options

# Force conventional commits mode
coco commit -c, --conventional

# Include/exclude branch name in context (default: true)
coco commit --include-branch-name
coco commit --no-include-branch-name

Processing Options

# Ignore specific files (can be used multiple times)
coco commit --ignored-files "*.lock" --ignored-files "dist/*"

# Ignore file extensions (can be used multiple times)  
coco commit --ignored-extensions ".map" --ignored-extensions ".min.js"

# Use basic git status instead of full diff (faster for large changes)
coco commit --no-diff

# Open commit message in editor before proceeding
coco commit --open-in-editor

# Skip pre-commit and commit-msg hooks (passes --no-verify to git commit)
coco commit -n, --no-verify

Examples

# Basic conventional commit
coco commit --conventional
# Output: feat: add user authentication system

# With scope and context
coco commit --conventional -a "fixes login timeout"
# Output: fix(auth): resolve login timeout issue

# With additional context and ticket
coco commit --conventional --additional "Resolves login issues" --append-ticket
# Output: feat(auth): add OAuth2 integration
#         
#         Implement OAuth2 flow with Google and GitHub providers.
#         Resolves login issues
#         
#         Part of **PROJ-123**

coco commit split

Split staged changes into multiple coherent commits. This is useful when you have a broad set of staged changes that logically belong in separate commits.

# Generate a split plan (non-mutating — reads staged changes and proposes groups)
coco commit split --plan

# Apply a generated plan (creates one commit per group)
coco commit split --apply

# Shorthand: --split is equivalent to --plan
coco commit --split

How It Works

--plan reads your staged changes, condenses the diffs, builds a hunk inventory for modified files, and asks the configured model to group files (or individual hunks) into proposed commits. It prints the plan but does not change git state.

--apply starts from a generated plan and creates one commit per group:

  • Whole-file groups stage the listed files. If a planned file also has unstaged or untracked changes, apply aborts for that group to avoid mixing unrelated work.
  • Hunk groups apply selected staged hunks directly to the index with git apply --cached, allowing separate commits from different parts of the same file.

Safety Rules

  • Every staged file must appear exactly once in the plan.
  • A file is assigned either as a whole file or by all of its hunk IDs, never both.
  • If a file is split by hunks, every generated hunk must be assigned exactly once.
  • Hunk-level apply is fail-closed: if a patch cannot be applied cleanly after earlier split commits have changed the file, the command stops and leaves remaining changes for manual review.

Configuration

coco commit split requires a configured AI provider. Pass -i (or set "mode": "interactive" in your config) so the plan is displayed for review:

coco commit split --plan -i

Examples

# Stage everything and generate a split plan
git add .
coco commit split --plan -i

# Review the plan, then apply it
coco commit split --apply -i

coco amend

Regenerate the last commit's message from its diff and rewrite it via git commit --amend.

# Regenerate the last commit message and amend in place
coco amend

Any currently-staged changes are folded into the amend (just as git commit --amend does), and the regenerated message reflects the combined diff. When staged changes are present, coco prints a note that they will be included before amending. If there is no commit to amend, the command exits non-zero.

Options

# Review the regenerated message, then apply / edit in $EDITOR / cancel
coco amend -i, --interactive

# Print the regenerated message without amending
coco amend --dry-run

# Emit { previous, message } as JSON without amending
coco amend --json

# Force conventional commits mode
coco amend -c, --conventional

# Add extra context to guide regeneration
coco amend -a, --additional "Clarify the rate-limit fix"

# Skip pre-commit and commit-msg hooks (passes --no-verify to git commit)
coco amend -n, --noVerify

Examples

# Tweak the message of the commit you just made
coco amend -i

# Stage a forgotten file, then fold it into the last commit with a fresh message
git add src/forgotten.ts
coco amend

# Preview what the new message would be without touching history
coco amend --dry-run

coco changelog

Creates changelogs from commit history.

# Basic changelog for current branch
coco changelog

# Interactive mode
coco changelog -i, --interactive

Range Selection Options

# Specific commit range (HEAD references)
coco changelog -r HEAD~5:HEAD

# Specific commit range (commit hashes)  
coco changelog -r abc1234:def5678

# Compare against target branch
coco changelog -b main, --branch main

# Compare against a tag
coco changelog -t 3.0.0, --tag 3.0.0

# All commits since last tag
coco changelog --since-last-tag

--branch, --tag, and --since-last-tag cannot be combined in the same run.

Content Options

# Include diff for each commit in analysis
coco changelog --with-diff

# Generate changelog based only on branch diff
coco changelog --only-diff

# Include author attribution
coco changelog --author

# Add extra context to guide generation
coco changelog -a "Focus on user-facing changes"

coco pr create

Generate a PR title and body from the current branch's diff against the base branch (reusing the changelog generator) and open it with the matching forge CLI.

# Generate a PR for the current branch and open it
coco pr create

coco auto-detects the forge (GitHub, GitHub Enterprise, or GitLab) from the git remote host, auto-detects the base branch, and checks whether the matching CLI is available — gh for GitHub / GitHub Enterprise, glab for GitLab. On GitLab this creates a merge request and pushes the source branch automatically. It refuses to run from the base branch, and exits 0 (a no-op) if a PR / MR already exists for the branch.

Options

# Target a specific base branch (default: repo default branch)
coco pr create -b main, --base main

# Open as a draft PR
coco pr create -d, --draft

# Override the generated title / body
coco pr create --title "Add OAuth2 login" --body "Implements the PKCE flow."

# Open the PR in the browser after creating it
coco pr create -w, --web

# Review / edit the generated title and body before creating
coco pr create -i, --interactive

# Print the generated PR without creating it
coco pr create --dry-run

# Emit the generated PR as JSON without creating it
coco pr create --json

Examples

# Generate and open a PR against main
coco pr create -b main -w

# Review the generated content before it's submitted
coco pr create -i

# Preview the title + body without calling gh
coco pr create --dry-run

coco recap

Summarize changes across different time periods.

# Summarize current working directory changes
coco recap

# Interactive mode
coco recap -i, --interactive

Time Period Options

# Yesterday's changes
coco recap --yesterday

# Last week's changes  
coco recap --last-week, --week

# Last month's changes
coco recap --last-month, --month

# Changes since last git tag
coco recap --last-tag, --tag

# Current branch changes
coco recap --current-branch

coco review

Perform AI-powered code review on your changes.

# Review current working directory changes
coco review

# Interactive mode
coco review -i, --interactive

# Review specific branch
coco review -b feature-branch, --branch feature-branch

# Scope the review to staged changes only
coco review --staged

# Exit non-zero when any finding is at or above the threshold (1-10) — for CI gating
coco review --severity 7

--severity <n> makes coco review fail the process when any finding's severity is at or above <n>, so it can gate a CI pipeline. --staged limits the review to the staged diff. Pair with the global --json flag for machine-readable findings.

coco ui

Open the full-screen Git workstation TUI.

# Start in history mode
coco ui

# Start in status or diff mode
coco ui --view status
coco ui --view diff

# Apply history filters before opening
coco ui --all
coco ui --branch feature/my-branch
coco ui --path src --limit 500

# Pick a theme preset
coco ui --theme catppuccin

coco ui supports:

  • sixteen top-level views — history, status, diff, compose, branches, tags, stash, worktrees, pull-request, PR triage, issues, conflicts, reflog, bisect, submodules, and changelog — reachable from any other view via g-prefixed chords (g h/g s/g d/g c/g b/g t/g z, and so on),
  • a navigation stack with < / Esc to pop back, plus a ›-separated breadcrumb in the header,
  • file-level and hunk-level stage/unstage with confirmation-gated revert,
  • commit compose as a top-level view with editable summary/body, hook feedback, and explicit AI commit draft generation,
  • an interactive command palette (:) with fuzzy filter and recently-used at the top, runnable from any view,
  • / global search across history, branches, tags, and stash,
  • a full stash workflow — an aligned table (ref · age · branch · files · message), gZ to stash from any view, and stash-view actions (R rename, b branch, A apply --index, u undo-drop),
  • a single-pane fallback for narrow terminals (under ~100 cols / 80×24 tmux splits): the panes fold to one full-width view you Tab between, with v to peek the sidebar.

See Coco UI for the full workstation guide and per-view actions.

coco log

Explore commit history with stdout, JSON, commit detail, and full-screen interactive TUI modes.

# Compact first-parent history
coco log

# Interactive terminal UI, equivalent to coco ui --view history
coco log -i, --interactive

# Full graph across all local and remote refs
coco log --all --view full

# Machine-readable output
coco log --format json

# Single commit metadata and changed files
coco log --commit HEAD

History Selection Options

# Limit loaded commits
coco log --limit 100

# Choose compact, graph, or full view
coco log --view compact
coco log --view graph
coco log --view full

# Include all refs
coco log --all

# Show a specific branch/ref
coco log --branch feature/my-branch

# Include or exclude merge commits
coco log --merges
coco log --no-merges

Plain stdout and JSON modes default to 30 commits. Interactive mode defaults to 300 commits so coco log -i has a broader browsing window. Passing --limit overrides either default.

Filter Options

# Filter by author
coco log --author "Grace Hopper"

# Filter by date range
coco log --since "2026-04-01" --until "2026-04-30"

# Filter by changed path
coco log --path src --path README.md

Interactive TUI

coco log -i opens coco ui --view history with:

  • repository/sidebar tabs for status, branches, tags, stashes, and worktrees,
  • a searchable commit graph/list,
  • selected commit metadata,
  • changed files, numstat totals, and selected-file hunk previews,
  • command palette, help panel, and confirmation prompts for advanced workflows.

Common keys:

Key Action
q, Ctrl+C Quit
/ Search/filter the active view
? Help (grouped Global / This view)
<, Esc Pop the navigation stack (back)
j / k, arrows Move in focused panel
g h/g s/g d/g c/g b/g t/g z Jump to history/status/diff/compose/branches/tags/stash
gg / G Jump to first/last visible commit
n / N Next/previous visible search result
Tab / Shift+Tab Move focus
[ / ] Cycle sidebar tabs
1-5 Jump to sidebar tabs
\ Toggle compact/full graph (was g before v0.34.0)
r Refresh repository context
: Open the interactive command palette

See Coco UI for the full workstation guide and Interactive Log TUI for the history-specific guide.

coco issues

List issues for the current repository — formatted table to stdout by default, with optional JSON output for scripting.

Works across GitHub, GitHub Enterprise, and GitLab — coco auto-detects the forge from the git remote host. Requires the matching CLI installed and authenticated: gh for GitHub / GitHub Enterprise, glab for GitLab (glab auth login).

# Open issues in the current repo
coco issues

# Filter by state
coco issues --state closed
coco issues --state all

# Filter by assignee / author
coco issues --assignee @me      # or --mine for shorthand
coco issues --author gfargo

# Filter by labels (comma-separated for AND)
coco issues --label bug,critical

# Free-form GitHub search syntax
coco issues --search "auth flow"

# Tune the page size
coco issues --limit 50

# Machine-readable output
coco issues --json | jq '.[] | .title'

The same flags and filters work on every forge. On GitLab, --mine / --author @me map to GitLab's scope filter.

Cache control

coco issues writes results to ~/.cache/coco/github/ (or $XDG_CACHE_HOME/coco/github/) with a 5-minute TTL. Triage tends to be bursty, so the cache pays for itself quickly.

# Force a fresh gh call (writes through to cache)
coco issues --refresh

# Skip the cache entirely (no read, no write)
coco issues --no-cache

# Clear the entire triage cache directory
coco cache clear-github

The repo header tag reads cached Ns ago on cache hits so you can always tell when a list is fresh vs warm.

coco prs

List pull requests for the current repository. Same shape as coco issues, with PR-specific filter knobs. Works across GitHub, GitHub Enterprise, and GitLab — on GitLab this lists merge requests. Requires gh (GitHub / GitHub Enterprise) or glab (GitLab) installed and authenticated.

# Open PRs (default)
coco prs

# State (PRs have a merged variant distinct from closed)
coco prs --state merged
coco prs --state all

# Targeting
coco prs --draft
coco prs --mine                 # = --author @me
coco prs --base main            # PRs targeting `main`
coco prs --head feature/auth    # PRs from `feature/auth`

# Cache flags work identically to `coco issues`
coco prs --refresh
coco prs --no-cache

Both commands are companion CLI entrypoints to the g i and g P triage chords inside coco ui. See Issue & PR Triage for the full action key reference, filter preset cycling, and inspector hydration details, and Multi-Forge Support for forge detection and the gh / glab requirements.

coco init

Interactive setup wizard for configuring coco.

# Setup wizard (will prompt for scope)
coco init

# Configure for current project only
coco init --scope project

# Configure globally for current user
coco init --scope global

coco doctor

Check your configuration for common issues and suggest fixes.

# Run diagnostics
coco doctor

# Auto-fix what can be fixed
coco doctor --fix

# Show the per-task model routing profile (and usage, when enabled)
coco doctor --cost

# Delete the local usage-stats ledger
coco doctor --clear

coco doctor inspects your merged configuration (project file, git config, env vars, defaults) and reports:

  • Errors: missing provider, missing API key, invalid JSON in config file
  • Warnings: outdated model names with newer replacements, Ollama misconfiguration, low token limits, placeholder API keys
  • Info: mode set to stdout (interactive features need -i), dynamic routing status, missing $schema field

With --fix, it writes auto-fixable changes (model upgrades, Ollama auth cleanup, token limit bumps, $schema addition) directly to .coco.config.json.

This is useful when upgrading coco versions — run coco doctor after updating to see if your config needs attention.

coco doctor --cost

--cost prints the per-task model routing profile — which model each of the eight dynamic-model tasks (summarize, commit, commitSplit, changelog, review, recap, repair, largeDiff) resolves to under the active preference.

When usage recording is enabled, it also prints aggregated token and latency usage by task, model, and repo from a cross-run ledger. As of 0.69 recording is opt-out and local-only: the first interactive run defaults it on after a one-time notice, coco init asks, and the data never leaves your machine (it records no prompt, diff, or code content). Opt out anytime with coco init, telemetry.usage: false, or COCO_USAGE_LOG=0. See Local usage stats for the full story. Add --json for machine-readable output (it includes a byRepo array).

coco doctor --clear deletes the local usage ledger.

# Just the routing profile (works with no usage history)
coco doctor --cost

# Routing profile plus aggregated usage by task, model, and repo
coco doctor --cost

# Machine-readable (includes byRepo)
coco doctor --cost --json

# Delete the local usage-stats ledger
coco doctor --clear

Global Options

These options work with all commands — they're inherited at the yargs root, so any subcommand sees them:

# Target a specific repository directory (alias: --cwd)
# Lets you drive coco against any repo without `cd`-ing first.
# Every command — commit, log, ui, recap, changelog, review,
# cache, doctor, init — respects this.
--repo <dir>

# Verbose output for debugging
--verbose

# Interactive mode (where supported)
-i, --interactive

# Machine-readable output where supported (changelog, recap, review,
# plus the --json flags on amend, pr create, doctor --cost)
--json

# Suppress status chrome (spinners, banners) but keep the result
-q, --quiet

# Display help
--help

# Display version
--version

--json emits structured output on the commands that support it (changelog, recap, review, plus the dedicated --json flags on coco amend, coco pr create, and coco doctor --cost). -q / --quiet strips status chrome so only the result reaches stdout — handy when piping into other tools.

--repo examples

# Generate a commit message for another project from your current shell
coco commit --repo ~/work/api

# Open the workstation against any repo without cd
coco ui --repo ~/work/api

# Inspect another repo's log
coco log --repo ~/work/api --limit 10

# Run the doctor against a specific project
coco doctor --repo ~/work/api

# Initialize a project config without cd
coco init --repo ~/work/api --scope project

# All of the above also accept `--cwd` as an alias
coco commit --cwd ~/work/api

When --repo is set, coco chdirs to the path up-front and binds its git instance to it, so config lookup, commitlint discovery, simple-git operations, and downstream path resolution all see the same root.

Common Workflows

Daily Development

# Make changes
git add .

# Generate and review commit
coco commit -i

Team Workflow with Validation

# Stage changes
git add .

# Generate conventional commit with ticket
coco commit --conventional --append-ticket -i

Release Workflow

# Generate changelog for release
coco changelog --since-last-tag

# Review recent release history interactively
coco log -i --since "2026-04-01"

# Create release commit
git add .
coco commit --conventional -a "Release version 1.2.0"

Code Review Workflow

# Review changes before committing
coco review

# Generate commit after review
coco commit --conventional -i

Output Modes

Stdout Mode (Default)

# Generate message to stdout
coco commit

# Use with git commit
git commit -m "$(coco commit)"

# Pipe to git commit
coco commit | git commit -F -

Interactive Mode

# Review and edit before committing
coco commit -i

# Set as default in config
{
  "mode": "interactive"
}

Configuration Integration

All commands respect your configuration settings:

# Use project config
coco commit  # Uses .coco.config.json settings

# Override with environment variables
COCO_MODE=interactive coco commit

# Override with command line flags
coco commit --conventional --interactive

For complete configuration options, see the Configuration Overview.

Clone this wiki locally