CLI tool for Basecamp 4 API - CRUD for projects, messages, documents, and people
npm install dc-basecamp-cliA TypeScript CLI tool for Basecamp 4 API with full CRUD operations for projects, messages, documents, and people.
``bash
cd basecamp-cli
npm install
npm run build
Configuration
Set environment variables:
`bash
export ACCESS_TOKEN="your_oauth2_token"
export ACCOUNT_ID="999999999"
export USER_AGENT="MyApp (contact@example.com)" # Optional
`Or create a
.env file:`bash
ACCESS_TOKEN=your_oauth2_token
ACCOUNT_ID=999999999
USER_AGENT=MyApp (contact@example.com)
`Quick Start
`bash
Test connection
basecamp testList projects
basecamp projects listGet project details and dock tool IDs
basecamp projects get 2085958499
basecamp projects tools 2085958499Create a project
basecamp projects create "New Project" --description "Project description"Post a message (auto-detects message board)
basecamp messages create 2085958499 \
--subject "Hello Team" \
--content "Welcome to the project!"Create a document (auto-detects vault)
basecamp docs create 2085958499 \
--title "Project Charter" \
--content "Overview
Key goals...
"List people
basecamp people listAdd person to project
basecamp people add 2085958499 \
--name "Jane Smith" \
--email "jane@example.com"List your assignments
basecamp my assignmentsList to-do lists and items for a project
basecamp todos list 2085958499
`Commands
$3
`bash
basecamp projects list [--status active|archived|trashed] [--json]
basecamp projects get [--json]
basecamp projects create [--description ] [--json]
basecamp projects update [--name ] [--description ] [--json]
basecamp projects delete [--force]
basecamp projects tools [--json]
basecamp projects export [--out ]
`$3
`bash
basecamp messages list [--board-id ] [--json]
basecamp messages get [--json]
basecamp messages create --subject --content [--board-id ] [--json]
basecamp messages update [--subject ] [--content ] [--json]
basecamp messages delete [--force]
`$3
`bash
basecamp docs list [--vault-id ] [--json]
basecamp docs get [--json]
basecamp docs create --title --content [--vault-id ] [--json]
basecamp docs update [--title ] [--content ] [--json]
basecamp docs delete [--force]
`$3
`bash
basecamp todos list [--list-id ] [--json]
basecamp todos create-list [--description ] [--json]
basecamp todos create [--description ] [--json]
basecamp todos complete
basecamp todos uncomplete
`$3
`bash
basecamp checkins list [--json]
basecamp checkins answer [--content ] [--json]
`$3
`bash
basecamp my assignments [--json]
`$3
`bash
basecamp people list [--json]
basecamp people get [--json]
basecamp people me [--json]
basecamp people in-project [--json]
basecamp people grant --ids
basecamp people revoke --ids [--force]
basecamp people add --name --email [--title ] [--company ]
`$3
`bash
basecamp test [--json] # Test API connection
basecamp config [--json] # Show configuration (tokens masked)
`Output Modes
- Default: Human-readable tables and formatted output
- --json: Machine-readable JSON for scripting
- Piped: Automatically detects non-TTY and outputs plain text
- Smart Markdown: Omit
--content for messages/docs to open an editor and convert Markdown to HTMLError Handling
The CLI handles common API errors:
- 401: Invalid or expired token
- 404: Resource not found (not retried)
- 429: Rate limited (shows retry-after time)
- 500-504: Server errors (retryable)
Development
`bash
Install dependencies
npm installType check
npm run typecheckBuild
npm run buildRun in development
npm run dev -- projects list
`Architecture
`
basecamp-cli/
├── src/
│ ├── index.ts # Main entry point
│ ├── api.ts # Basecamp API client
│ ├── config.ts # Configuration loading
│ ├── output.ts # Terminal output formatting
│ ├── types.ts # TypeScript types
│ └── commands/
│ ├── projects.ts # Project CRUD
│ ├── messages.ts # Message CRUD
│ ├── documents.ts # Document CRUD
│ └── people.ts # People CRUD
│ ├── my.ts # Current user commands
│ └── todos.ts # To-do lists and items
│ └── utils/
│ ├── editor.ts # Open editor for smart markdown
│ └── markdown.ts # Markdown to HTML conversion
├── package.json
└── tsconfig.json
``MIT