dc-basecamp-cli

v1.2.0

Published

6 days ago

CLI tool for Basecamp 4 API - CRUD for projects, messages, documents, and people

0High
0Medium
0Low

dallasdotjs

basecamp cli api project-management

Basecamp CLI

A TypeScript CLI tool for Basecamp 4 API with full CRUD operations for projects, messages, documents, and people.

Installation

cd basecamp-cli
npm install
npm run build

# Run directly
node dist/index.js --help

# Or link globally
npm link
basecamp --help

Configuration

Set environment variables:

export ACCESS_TOKEN="your_oauth2_token"
export ACCOUNT_ID="999999999"
export USER_AGENT="MyApp ([email protected])"  # Optional

Or create a .env file:

ACCESS_TOKEN=your_oauth2_token
ACCOUNT_ID=999999999
USER_AGENT=MyApp ([email protected])

Quick Start

# Test connection
basecamp test

# List projects
basecamp projects list

# Get project details and dock tool IDs
basecamp projects get 2085958499
basecamp projects tools 2085958499

# Create 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 "<div>Welcome to the project!</div>"

# Create a document (auto-detects vault)
basecamp docs create 2085958499 \
  --title "Project Charter" \
  --content "<h1>Overview</h1><p>Key goals...</p>"

# List people
basecamp people list

# Add person to project
basecamp people add 2085958499 \
  --name "Jane Smith" \
  --email "[email protected]"

# List your assignments
basecamp my assignments

# List to-do lists and items for a project
basecamp todos list 2085958499

Commands

Projects

basecamp projects list [--status active|archived|trashed] [--json]
basecamp projects get <id> [--json]
basecamp projects create <name> [--description <text>] [--json]
basecamp projects update <id> [--name <name>] [--description <text>] [--json]
basecamp projects delete <id> [--force]
basecamp projects tools <id> [--json]
basecamp projects export <id> [--out <dir>]

Messages

basecamp messages list <project-id> [--board-id <id>] [--json]
basecamp messages get <project-id> <message-id> [--json]
basecamp messages create <project-id> --subject <text> --content <html> [--board-id <id>] [--json]
basecamp messages update <project-id> <message-id> [--subject <text>] [--content <html>] [--json]
basecamp messages delete <project-id> <message-id> [--force]

Documents

basecamp docs list <project-id> [--vault-id <id>] [--json]
basecamp docs get <project-id> <document-id> [--json]
basecamp docs create <project-id> --title <text> --content <html> [--vault-id <id>] [--json]
basecamp docs update <project-id> <document-id> [--title <text>] [--content <html>] [--json]
basecamp docs delete <project-id> <document-id> [--force]

To-Dos

basecamp todos list <project-id> [--list-id <id>] [--json]
basecamp todos create-list <project-id> <name> [--description <html>] [--json]
basecamp todos create <project-id> <list-id> <content> [--description <html>] [--json]
basecamp todos complete <project-id> <todo-id>
basecamp todos uncomplete <project-id> <todo-id>

Check-ins

basecamp checkins list <project-id> [--json]
basecamp checkins answer <project-id> <question-id> [--content <html>] [--json]

My

basecamp my assignments [--json]

People/Clients

basecamp people list [--json]
basecamp people get <id> [--json]
basecamp people me [--json]
basecamp people in-project <project-id> [--json]
basecamp people grant <project-id> --ids <comma-separated-ids>
basecamp people revoke <project-id> --ids <comma-separated-ids> [--force]
basecamp people add <project-id> --name <name> --email <email> [--title <title>] [--company <company>]

Utility

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 HTML

Error 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

# Install dependencies
npm install

# Type check
npm run typecheck

# Build
npm run build

# Run 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

License

MIT