Skip to content

Command Reference

Jump to bottom
Griffen Fargo edited this page May 2, 2026 · 7 revisions

Command Reference

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

coco commit

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

coco
# or 
coco commit

Basic Options

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

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

# Help - display command help
coco --help

Commit Enhancement Options

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

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

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

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

Conventional Commits Options

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

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

Processing Options

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

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

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

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

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

Examples

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

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

# With additional context and ticket
coco --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 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 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

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:

  • seven top-level views — history, status, diff, compose, branches, tags, stash — reachable from any other view via g-prefixed chords (g h/g s/g d/g c/g b/g t/g z),
  • 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.

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 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

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.

Global Options

These options work with all commands:

# Verbose output for debugging
--verbose

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

# Display help
--help

# Display version
--version

Common Workflows

Daily Development

# Make changes
git add .

# Generate and review commit
coco -i

Team Workflow with Validation

# Stage changes
git add .

# Generate conventional commit with ticket
coco --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 --conventional -a "Release version 1.2.0"

Code Review Workflow

# Review changes before committing
coco review

# Generate commit after review
coco --conventional -i

Output Modes

Stdout Mode (Default)

# Generate message to stdout
coco

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

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

Interactive Mode

# Review and edit before committing
coco -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 --conventional --interactive commit

For complete configuration options, see the Configuration Overview.

Clone this wiki locally