README
¶
Basecamp CLI
basecamp is the official command-line interface for Basecamp. Manage projects, todos, messages, and more from your terminal or through AI agents.
- Works standalone or with any AI agent (Claude, Codex, Copilot, Gemini)
- JSON output with breadcrumbs for easy navigation
- OAuth authentication with automatic token refresh
Quick Start
brew install --cask basecamp/tap/basecamp
basecamp auth login
That's it. You now have full access to Basecamp from your terminal.
Other installation methods
Arch Linux / Omarchy (AUR):
yay -S basecamp-cli
Scoop (Windows):
scoop bucket add basecamp https://github.com/basecamp/homebrew-tap
scoop install basecamp
Shell script:
curl -fsSL https://raw.githubusercontent.com/basecamp/basecamp-cli/main/scripts/install.sh | bash
Go install:
go install github.com/basecamp/basecamp-cli/cmd/basecamp@latest
GitHub Release: download from Releases.
Usage
basecamp projects # List projects
basecamp todos --in 12345 # Todos in a project
basecamp todo --content "Fix bug" --in 12345 # Create todo
basecamp done 67890 # Complete todo
basecamp search "authentication" # Search across projects
basecamp cards --in 12345 # List cards (Kanban)
basecamp campfire post "Hello" --in 12345 # Post to chat
Output Formats
basecamp projects # Styled output in terminal, JSON when piped
basecamp projects --json # JSON with envelope and breadcrumbs
basecamp projects --quiet # Raw JSON data only
JSON Envelope
Every command supports --json for structured output:
{
"ok": true,
"data": [...],
"summary": "5 projects",
"breadcrumbs": [{"action": "show", "cmd": "basecamp projects show <id>"}]
}
Breadcrumbs suggest next commands, making it easy for humans and agents to navigate.
Authentication
OAuth 2.1 with automatic token refresh. First login opens your browser:
basecamp auth login # Read-only access (default)
basecamp auth login --scope full # Full read/write access
basecamp auth token # Print token for scripts
AI Agent Integration
basecamp works with any AI agent that can run shell commands.
Claude Code: claude plugin install basecamp — installs the plugin with skills, hooks, and agent workflow support.
Other agents: Point your agent at skills/basecamp/SKILL.md for Basecamp workflow coverage.
Agent discovery: Every command supports --help --agent for structured JSON output (flags, gotchas, subcommands). Use basecamp commands --json for the full catalog.
See install.md for step-by-step setup instructions.
Configuration
~/.config/basecamp/ # Your Basecamp identity
├── credentials.json # OAuth tokens (fallback when keyring unavailable)
├── client.json # DCR client registration
└── config.json # Global preferences
~/.config/basecamp/theme/ # Tool display (optional)
└── colors.toml # TUI color scheme
~/.cache/basecamp/ # Ephemeral tool data
├── completion.json # Tab completion cache
└── resilience/ # Circuit breaker state
.basecamp/ # Per-repo (committed to git)
└── config.json # Project, account defaults
Troubleshooting
basecamp doctor # Check CLI health and diagnose issues
basecamp doctor --verbose # Verbose output with details
Development
make build # Build binary
make test # Run Go tests
make test-e2e # Run e2e tests
make lint # Run linter
make check # All checks (fmt-check, vet, lint, test, test-e2e)
See CONTRIBUTING.md for development setup.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
basecamp
command
Package main is the entry point for the basecamp CLI.
|
Package main is the entry point for the basecamp CLI. |
|
internal
|
|
|
appctx
Package appctx provides application context helpers.
|
Package appctx provides application context helpers. |
|
auth
Package auth provides OAuth 2.1 authentication for Basecamp.
|
Package auth provides OAuth 2.1 authentication for Basecamp. |
|
commands
Package commands implements the CLI commands.
|
Package commands implements the CLI commands. |
|
completion
Package completion provides tab completion support for the basecamp CLI.
|
Package completion provides tab completion support for the basecamp CLI. |
|
config
Package config provides layered configuration loading.
|
Package config provides layered configuration loading. |
|
dateparse
Package dateparse provides natural language date parsing.
|
Package dateparse provides natural language date parsing. |
|
harness
Package harness detects and checks AI agent integration health.
|
Package harness detects and checks AI agent integration health. |
|
hostutil
Package hostutil provides shared utilities for host URL handling.
|
Package hostutil provides shared utilities for host URL handling. |
|
models
Package models provides canonical type definitions for Basecamp API entities.
|
Package models provides canonical type definitions for Basecamp API entities. |
|
names
Package names provides name resolution for projects, people, and todolists.
|
Package names provides name resolution for projects, people, and todolists. |
|
observability
Package observability provides metrics collection and tracing for CLI operations.
|
Package observability provides metrics collection and tracing for CLI operations. |
|
output
Package output provides JSON/Markdown output formatting and error handling.
|
Package output provides JSON/Markdown output formatting and error handling. |
|
presenter
Package presenter provides schema-aware rendering for Basecamp entities.
|
Package presenter provides schema-aware rendering for Basecamp entities. |
|
resilience
Package resilience provides cross-process state management for long-running CLI operations.
|
Package resilience provides cross-process state management for long-running CLI operations. |
|
richtext
Package richtext provides utilities for converting between Markdown and HTML.
|
Package richtext provides utilities for converting between Markdown and HTML. |
|
sdk
Package sdk provides core SDK interfaces for the Basecamp API client.
|
Package sdk provides core SDK interfaces for the Basecamp API client. |
|
sdk/errors
Package errors provides SDK error types without CLI-specific hints.
|
Package errors provides SDK error types without CLI-specific hints. |
|
tui
Package tui provides terminal user interface components.
|
Package tui provides terminal user interface components. |
|
tui/empty
Package empty provides empty state messages for TUI components.
|
Package empty provides empty state messages for TUI components. |
|
tui/format
Package format provides formatting helpers for TUI components.
|
Package format provides formatting helpers for TUI components. |
|
tui/recents
Package recents provides a store for tracking recently used items.
|
Package recents provides a store for tracking recently used items. |
|
tui/resolve
Package resolve provides interactive prompts for resolving missing CLI options.
|
Package resolve provides interactive prompts for resolving missing CLI options. |
|
tui/workspace
Package workspace provides the persistent TUI application.
|
Package workspace provides the persistent TUI application. |
|
tui/workspace/chrome
Package chrome provides always-visible shell components for the workspace.
|
Package chrome provides always-visible shell components for the workspace. |
|
tui/workspace/views
Package views provides the individual screens for the workspace TUI.
|
Package views provides the individual screens for the workspace TUI. |
|
tui/workspace/widget
Package widget provides reusable TUI components.
|
Package widget provides reusable TUI components. |
|
urlarg
Package urlarg provides utilities for parsing Basecamp URLs into IDs.
|
Package urlarg provides utilities for parsing Basecamp URLs into IDs. |
|
version
Package version provides build-time version information.
|
Package version provides build-time version information. |
|
Package skills embeds the skill files in the binary.
|
Package skills embeds the skill files in the binary. |
Click to show internal directories.
Click to hide internal directories.