Basecamp CLI
Command-line interface for Basecamp. All output is JSON.
Prerequisites
basecamp version # Verify installation
basecamp projects # Verify authentication (run `basecamp auth` if needed)
Project Context
Create .basecamp.yml in a directory to set default project:
project_id: 12345678
Then omit project_id from commands when in that directory.
Commands Reference
Projects & Boards
basecamp projects # List all projects
basecamp boards [project_id] # List card tables
basecamp columns [project_id] <board_id> # List columns in board
Cards
basecamp cards [project_id] <board_id> # List cards
basecamp cards [project_id] <board_id> --column "Name" # Filter by column
basecamp card [project_id] <card_id> # View card
basecamp card [project_id] <card_id> --comments # With comments
basecamp card-create [project_id] <board_id> --column <col_id> --title "Title"
basecamp card-update [project_id] <card_id> --title "New" --content "Text"
basecamp move [project_id] <board_id> <card_id> --to "Column Name"
Card Steps (Checklists)
basecamp step-create [project_id] <card_id> --title "Step"
basecamp step-create [project_id] <card_id> --title "Step" --due 2026-02-01 --assignees "123,456"
basecamp step-update [project_id] <step_id> --title "Updated"
basecamp step-complete [project_id] <step_id>
basecamp step-uncomplete [project_id] <step_id>
basecamp step-reposition [project_id] <card_id> <step_id> --position 0
Todos
basecamp todolists [project_id] # List todo lists
basecamp todos [project_id] <todolist_id> # List todos
basecamp todos [project_id] <todolist_id> --completed # Completed todos
basecamp todo [project_id] <todo_id> # View todo
basecamp todo-create [project_id] <list_id> --content "Task" --due 2026-02-01
basecamp todo-complete [project_id] <todo_id>
basecamp todo-uncomplete [project_id] <todo_id>
basecamp todo-reposition [project_id] <todo_id> --position 1
Todo Groups
basecamp todolist-groups [project_id] <todolist_id> # List groups
basecamp todolist-group [project_id] <group_id> # View group
basecamp todolist-group-create [project_id] <list_id> --name "Sprint 1" --color green
Messages
basecamp messages [project_id] # List messages
basecamp message [project_id] <message_id> # View message
basecamp message [project_id] <message_id> --comments # With comments
basecamp message-create [project_id] --subject "Subject" --content "Body"
Comments
basecamp comment-add [project_id] <recording_id> --content "Comment"
Documents
basecamp docs [project_id] # List documents
basecamp doc [project_id] <doc_id> # View document
basecamp doc [project_id] <doc_id> --comments # With comments
basecamp doc-create [project_id] --title "Title" --content "Content"
Schedule
basecamp schedule [project_id] # List entries
basecamp event [project_id] <entry_id> # View event
basecamp event [project_id] <entry_id> --comments # With comments
basecamp event-create [project_id] --summary "Meeting" --starts-at "2026-02-01T10:00:00Z" --ends-at "2026-02-01T11:00:00Z"
basecamp event-create [project_id] --summary "Holiday" --starts-at "2026-02-01" --ends-at "2026-02-01" --all-day
Campfire
basecamp campfire [project_id] # List messages
basecamp campfire-post [project_id] --content "Hello!"
Search
basecamp search "query" # Search all projects
basecamp search "query" --type Todo # Filter by type
basecamp search "query" --project <project_id> # Filter by project
Types: Todo, Message, Document, Kanban::Card, Schedule::Entry, Comment
People
basecamp people # List all people
basecamp person <person_id> # View person
basecamp people-pingable # Pingable people
basecamp people-project [project_id] # Project members
basecamp my-profile # Your profile
basecamp project-access [project_id] --grant "123,456" --revoke "789"
Automatic Check-ins
basecamp questionnaire [project_id] # Questionnaire info
basecamp questions [project_id] # List questions
basecamp question [project_id] <question_id> # View question
basecamp question [project_id] <question_id> --comments # With comments
basecamp question-answers [project_id] <question_id> # List answers
basecamp question-answer [project_id] <answer_id> # View answer
Uploads
basecamp upload /path/to/file.pdf # Upload file (returns sgid)
basecamp uploads [project_id] <vault_id> # List uploads in vault
basecamp upload-view [project_id] <upload_id> # View upload
basecamp upload-view [project_id] <upload_id> --comments # With comments
Recordings Management
basecamp archive [project_id] <recording_id> # Archive recording
basecamp unarchive [project_id] <recording_id> # Unarchive
basecamp trash [project_id] <recording_id> # Trash recording
Message Types
basecamp message-types [project_id] # List types
basecamp message-type [project_id] <type_id> # View type
basecamp message-type-create [project_id] --name "Announcement" --icon "📢"
basecamp message-type-update [project_id] <type_id> --name "Update" --icon "✅"
basecamp message-type-delete [project_id] <type_id>
Activity Events
basecamp events # All events
basecamp events-project [project_id] # Project events
basecamp events-recording [project_id] <recording_id> # Recording events
Error Handling
Errors return JSON to stderr:
{"error": "not authenticated, run 'basecamp auth' first"}
Tips
- All commands output JSON - pipe to
jqfor filtering - Use
--commentsflag to include comments on supported commands - Recording IDs work across types (todos, cards, messages, etc.)
- Get vault_id from
basecamp docsoutput for upload commands