home / skills / robzolkos / basecamp-cli / basecamp

basecamp skill

safe

This skill helps you manage Basecamp projects from the CLI, returning JSON results for cards, todos, messages, docs, and events.

npx playbooks add skill robzolkos/basecamp-cli --skill basecamp

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

6.8 KB

---
name: basecamp
description: Interact with Basecamp projects via CLI. Manage card tables, todos, messages, documents, schedules, campfires, people, check-ins, uploads, and more. Use when the user mentions Basecamp, cards, todos, messages, or project management.
---

# Basecamp CLI

Command-line interface for Basecamp. All output is JSON.

## Prerequisites

```bash
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:

```yaml
project_id: 12345678
```

Then omit project_id from commands when in that directory.

## Commands Reference

### Projects & Boards

```bash
basecamp projects                          # List all projects
basecamp boards [project_id]               # List card tables
basecamp columns [project_id] <board_id>   # List columns in board
```

### Cards

```bash
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)

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

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

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

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

```bash
basecamp comment-add [project_id] <recording_id> --content "Comment"
```

### Documents

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

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

```bash
basecamp campfire [project_id]                            # List messages
basecamp campfire-post [project_id] --content "Hello!"
```

### Search

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

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

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

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

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

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

```bash
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:

```json
{"error": "not authenticated, run 'basecamp auth' first"}
```

## Tips

- All commands output JSON - pipe to `jq` for filtering
- Use `--comments` flag to include comments on supported commands
- Recording IDs work across types (todos, cards, messages, etc.)
- Get vault_id from `basecamp docs` output for upload commands

Overview

This skill provides a command-line interface to interact with Basecamp projects and resources. It exposes JSON-output commands to list and manage projects, boards, cards, todos, messages, documents, schedules, people, uploads, and more. Use it to automate or script common Basecamp workflows from terminals and CI pipelines.

How this skill works

Commands talk to the Basecamp API and always return JSON, making output easy to parse with jq or other tools. You can set a default project per directory with a .basecamp.yml file so commands omit the project_id. Many commands accept flags like --comments, --completed, or --all-day and support creating, updating, moving, and archiving records.

When to use it

Automating project tasks or reporting from the terminal or CI
Scripting bulk updates to cards, todos, or checklists
Searching across projects for todos, messages, or documents
Uploading files to a project vault or listing vault contents
Managing project membership, check-ins, or scheduled events

Best practices

Confirm installation and authentication with 'basecamp version' and 'basecamp projects' before scripting
Create a .basecamp.yml in a workspace to set project_id and avoid repeating it
Pipe JSON output to jq for targeted fields and filtering in scripts
Use --comments on supported commands when you need discussion context
Treat recording IDs as reusable across cards, todos, messages, and other record types

Example use cases

List all cards on a board and move selected cards to another column in a script
Create todo lists and todos for a sprint kickoff, including due dates and assignees
Search across projects for a keyword and export matching todos, messages, and documents
Upload a build artifact to a project vault and record the returned sgid for tracking
Automate daily check-ins by listing questions and posting answers programmatically

FAQ

How do I avoid passing project_id every time?

Place a .basecamp.yml with project_id in your working directory; commands will use that project by default.

What format does the CLI return?

All commands output JSON to stdout; errors are returned as JSON to stderr.

Can I include comments when viewing records?

Yes. Many view commands accept --comments to include associated comments in the output.