coding-friend-cli

CLI companion for the coding-friend plugin — a lean toolkit for disciplined engineering workflows with Claude Code and Codex CLI.

Plugin without the CLI?

If you installed the Coding Friend plugin through the Claude Code marketplace but cannot install or run this CLI (npm errors, sandboxed environment, restricted machine), the plugin still works. You lose:

• Fast indexed memory search — falls back to grep -r '<query>' docs/memory/
• The coding-friend-learn-host doc viewer — open docs/learn/*.md directly in your editor
• The cf statusline renderer — Claude Code's default statusline takes over

Everything else (every skill, every agent, every hook except the three OPTIONAL hooks above) is unaffected. See ../docs/cli-requirements.md for the full matrix.

Common CLI install issues

• node not found — install Node.js 20+ from https://nodejs.org (the CLI declares engines.node >= 20; older versions will refuse to install).
• EACCES on global install — set a user-writable global prefix: npm config set prefix ~/.npm-global and add ~/.npm-global/bin to your PATH.
• cf not on PATH after install — verify with npm root -g and ensure that directory's bin/ is in your PATH.
• MCP server not appearing in Claude Code — after install, run cf mcp to register both Learn and Memory MCP at user scope, then restart Claude Code.

Requirements

• Node.js >= 20
• npm (included with Node.js, but on some Linux distros you may need to install it separately)
• The coding-friend plugin installed in Claude Code or Codex CLI

Additional requirements for cf memory init

The memory system's Tier 1 (SQLite) uses native Node.js modules that require compilation. On Linux (Ubuntu/Debian), install the following system packages before running cf memory init:

sudo apt update
sudo apt install -y build-essential python3

On macOS, install Xcode Command Line Tools:

xcode-select --install

Without these, cf memory init will fail when installing SQLite dependencies (better-sqlite3, sqlite-vec). If you don't need Tier 1, you can choose the lite (Tier 2) or markdown (Tier 3) tier during init — these have no native dependencies.

Install

npm i -g coding-friend-cli

Commands

cf install              # Install plugin (interactive scope chooser)
cf install --user       # Install at user scope (all projects)
cf install --global     # Same as --user
cf install --project    # Install at project scope (shared via git)
cf install --local      # Install at local scope (this machine only)
cf install --agent codex  # Register/install Coding Friend for Codex CLI
cf install --agent agy    # Google Antigravity (beta); alias --agy
cf install --agent devin  # Devin CLI (beta); alias --devin
                        # 💡 Safe to run multiple times (idempotent).
cf uninstall            # Uninstall plugin (interactive scope chooser)
cf uninstall --user     # Uninstall from user scope (full cleanup)
cf uninstall --global   # Same as --user
cf uninstall --project  # Uninstall from project scope only
cf uninstall --local    # Uninstall from local scope only
cf uninstall --agent codex  # Disable Coding Friend in Codex CLI
cf uninstall --agent agy    # Google Antigravity (beta); alias --agy
cf uninstall --agent devin  # Devin CLI (beta); alias --devin
                        # 💡 Interactive — asks for confirmation before acting.
cf disable             # Disable plugin (interactive scope chooser)
cf disable --user      # Disable at user scope (all projects)
cf disable --global    # Same as --user
cf disable --project   # Disable at project scope
cf disable --local     # Disable at local scope
                       # 💡 Plugin stays installed but won't load.
cf enable              # Re-enable plugin (interactive scope chooser)
cf enable --user       # Enable at user scope (all projects)
cf enable --global     # Same as --user
cf enable --project    # Enable at project scope
cf enable --local      # Enable at local scope
cf enable --agent devin
                       # 💡 Devin CLI (beta) has no per-plugin enable/disable —
                       #    cf prints guidance instead (alias --devin; same on cf disable).
cf init              # Initialize workspace (interactive)
cf init --agent codex  # Initialize workspace for Codex CLI
cf init --agent agy    # Google Antigravity (beta); alias --agy
cf init --agent devin  # Devin CLI (beta); alias --devin
                     # 💡 You can run this anywhere, anytime.
cf config            # Manage Coding Friend configuration (interactive menu)
                     # 💡 Edit docsDir, language, learn settings, and more.
cf learn host [path] # Build and serve learning docs at localhost:3333
                     # [path] is optional, default is `~/.coding-friend/learn`
cf learn push [path] # Commit and push learning docs (only if learn dir is the git root)
                     # [path] is optional, default is `~/.coding-friend/learn`
cf mcp [path]        # Setup MCP server for LLM integration
                     # [path] is optional, default is `~/.coding-friend/learn`
                     # This prints a JSON config snippet to add to your client's MCP
                     # Also reports Devin plugin MCP status (no --agent flag on cf mcp)
cf permission              # Manage Claude Code permission rules (interactive)
cf permission --all        # Apply all recommended permissions without prompts
cf permission --user       # Save to user-level settings (~/.claude/settings.json)
cf permission --project    # Save to project-level settings (.claude/settings.local.json)
cf permission --agent codex --enable-auto-approve
cf permission --agent agy  # Antigravity (beta); alias --agy
cf permission --agent devin # Devin CLI (beta); alias --devin
cf permission --all --user # Apply all recommended permissions to user settings
cf statusline        # Setup coding-friend statusline
cf update               # Update plugin + CLI + statusline
                        # 💡 If update fails, open Claude Code (`claude`) and run:
                        #    /plugins → Installed → coding-friend → Update now → /reload-plugins
cf update --cli         # Update only the CLI (npm package)
cf update --plugin      # Update only the Claude Code plugin
cf update --statusline  # Update only the statusline
cf update --agent codex # Update Codex marketplace/plugin cache
cf update --agent agy   # Google Antigravity (beta); alias --agy
cf update --agent devin # Devin CLI (beta); alias --devin
cf update --project     # Update plugin at project scope
cf update --local       # Update plugin at local scope
cf dev on [path]     # Switch to local plugin source for development
cf dev off           # Switch back to remote marketplace
cf dev status        # Show current dev mode (local or remote)
cf dev sync          # Sync local changes to cache (no version bump needed)
cf dev restart       # Reinstall local dev plugin (off + on)
cf dev update        # Update local dev plugin to latest version (off + on)
cf memory status     # Show memory system status and stats
cf memory search     # Search memories by keyword
cf memory list              # List all memories in current project
cf memory list --projects   # List all project databases with size and metadata
cf memory rm --project-id <id>  # Remove a specific project database
cf memory rm --all          # Remove all project databases
cf memory rm --prune        # Remove orphaned projects (source dir missing or 0 memories)
cf memory start-daemon  # Start memory daemon (enables Tier 2 search)
cf memory stop-daemon   # Stop memory daemon
cf memory rebuild    # Rebuild search index from markdown files
cf memory init       # Initialize memory system (interactive wizard)
cf memory config     # Configure memory system settings
cf memory mcp        # Show MCP server config for clients
cf status            # Show comprehensive Coding Friend status
                     # (versions, per-host plugin state incl. Devin, memory, config)
cf clean             # Clean files generated by Coding Friend in docs/
cf session save      # Save current Claude Code session to docs/sessions/
cf session load      # Load a saved session from docs/sessions/
cf help              # Show all commands

🐳 CLI Development

To work on the CLI locally:

cd cli
npm install
npm run build
npm link            # Creates global symlink for `cf` binary

Now cf is available globally, pointing to your local source. After making changes:

npm run build       # Rebuild (no need to re-link)
npm run watch       # Auto-rebuild on file changes

For development without rebuilding:

npm run dev -- <command>   # e.g. npm run dev -- init

To unlink when done:

npm unlink -g coding-friend-cli

To check if cf is pointing to the local plugin source:

npm ls -g coding-friend-cli
# Result:
# /Users/thi/.nvm/versions/node/v22.21.1/lib
#└── [email protected] -> ./../../../../../git/coding-friend/cli

Running tests

Tests are written with Vitest.

cd cli

# Run all unit tests once
npm test

# Watch mode (re-runs on file changes)
npm run test:watch

# Run E2E tests (real CLI commands against temp directories)
npm run test:e2e

# Run E2E tests in Docker (isolated, no host pollution)
cd e2e && docker compose up --build --abort-on-container-exit

Unit tests live in src/**/__tests__/ and use mocks. E2E tests live in e2e/ and run actual CLI commands — see e2e/README.md for details.

Publish CLI to npm

Publishing is automated via GitHub Actions (.github/workflows/publish-cli.yml). Push a tag with the cli-v* prefix to trigger it:

# Bump version in cli/package.json first, then tag and push
git tag cli-v1.2.3
git push origin cli-v1.2.3

The workflow will build, bundle, and publish to npm automatically (with provenance), then create a GitHub Release with the changelog for that version.

Manual publish (if needed):

cd cli
npm login              # Login if not already
npm publish            # Build + bundle + publish

prepublishOnly runs automatically: builds TypeScript → dist/ and bundles libs from lib/.

• Bump version in cli/package.json before publishing
• First time or public package: npm publish --access public
• Package name: coding-friend-cli → users install with npm i -g coding-friend-cli

License

MIT