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
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 <company>]<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">bash<br />basecamp test [--json] # Test API connection<br />basecamp config [--json] # Show configuration (tokens masked)<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Output Modes</h2></p><p class="my-3">- <strong>Default</strong>: Human-readable tables and formatted output<br />- <strong>--json</strong>: Machine-readable JSON for scripting<br />- <strong>Piped</strong>: Automatically detects non-TTY and outputs plain text<br />- <strong>Smart Markdown</strong>: Omit </code>--content<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> for messages/docs to open an editor and convert Markdown to HTML</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Error Handling</h2></p><p class="my-3">The CLI handles common API errors:</p><p class="my-3">- <strong>401</strong>: Invalid or expired token<br />- <strong>404</strong>: Resource not found (not retried)<br />- <strong>429</strong>: Rate limited (shows retry-after time)<br />- <strong>500-504</strong>: Server errors (retryable)</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Development</h2></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">bash<br /><h1 class="text-2xl font-bold mt-6 mb-4">Install dependencies</h1><br />npm install</p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">Type check</h1><br />npm run typecheck</p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">Build</h1><br />npm run build</p><p class="my-3"><h1 class="text-2xl font-bold mt-6 mb-4">Run in development</h1><br />npm run dev -- projects list<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Architecture</h2></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />basecamp-cli/<br />├── src/<br />│ ├── index.ts # Main entry point<br />│ ├── api.ts # Basecamp API client<br />│ ├── config.ts # Configuration loading<br />│ ├── output.ts # Terminal output formatting<br />│ ├── types.ts # TypeScript types<br />│ └── commands/<br />│ ├── projects.ts # Project CRUD<br />│ ├── messages.ts # Message CRUD<br />│ ├── documents.ts # Document CRUD<br />│ └── people.ts # People CRUD<br />│ ├── my.ts # Current user commands<br />│ └── todos.ts # To-do lists and items<br />│ └── utils/<br />│ ├── editor.ts # Open editor for smart markdown<br />│ └── markdown.ts # Markdown to HTML conversion<br />├── package.json<br />└── tsconfig.json<br /></code>``</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">License</h2></p><p class="my-3">MIT<br /></p></div><div class="flex justify-center absolute inset-x-0 bottom-0 bg-gradient-to-t from-background via-background to-transparent pb-4 pt-16"><button data-slot="button" class="inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down mr-1 h-4 w-4"><path d="m6 9 6 6 6-6"></path></svg>Show more</button></div></div></div><template id="P:3"></template><template id="P:4"></template></div></div></div><script>self.__next_f.push([1,"25:[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}]\n26:[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^12.0.0\"}]\n27:[\"$\",\"$L5\",\"dotenv\",{\"href\":\"/package/dotenv\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"dotenv\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^16.4.0\"}]]}]\n28:[\"$\",\"$L5\",\"marked\",{\"href\":\"/package/marked\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"marked\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^15.0.12\"}]]}]\n29:[\"$\",\"$L5\",\"ora\",{\"href\":\"/package/ora\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"ora\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^8.0.0\"}]]}]\n2a:[\"$\",\"$L5\",\"turndown\",{\"href\":\"/package/turndown\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"turndown\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^7.2.2\"}]]}]\n"])</script><script>self.__next_f.push([1,"2b:[\"$\",\"div\",null,{\"data-slot\":\"card\",\"className\":\"bg-card text-card-foreground flex flex-col gap-6 rounded-xl border shadow-sm py-4 lg:col-span-2\",\"children\":[[\"$\",\"div\",null,{\"data-slot\":\"card-header\",\"className\":\"@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6 pb-2\",\"children\":[\"$\",\"div\",null,{\"data-slot\":\"card-title\",\"className\":\"font-semibold flex items-center gap-2 text-base\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-wrench h-4 w-4\",\"children\":[[\"$\",\"path\",\"cbrjhi\",{\"d\":\"M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z\"}],\"$undefined\"]}],\"Dev Dependencies\",[\"$\",\"span\",null,{\"data-slot\":\"badge\",\"className\":\"inline-flex items-center justify-center rounded-md border px-2 py-0.5 font-medium w-fit whitespace-nowrap shrink-0 [\u0026\u003esvg]:size-3 gap-1 [\u0026\u003esvg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden border-transparent bg-secondary text-secondary-foreground [a\u0026]:hover:bg-secondary/90 ml-auto text-xs\",\"children\":6}]]}]}],[\"$\",\"div\",null,{\"data-slot\":\"card-content\",\"className\":\"px-6\",\"children\":[\"$\",\"div\",null,{\"className\":\"grid gap-1 sm:grid-cols-2 lg:grid-cols-3\",\"children\":[[\"$\",\"$L5\",\"@biomejs/biome\",{\"href\":\"/package/%40biomejs%2Fbiome\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"@biomejs/biome\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^1.9.0\"}]]}],[\"$\",\"$L5\",\"@types/node\",{\"href\":\"/package/%40types%2Fnode\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"@types/node\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^20.0.0\"}]]}],[\"$\",\"$L5\",\"@types/turndown\",{\"href\":\"/package/%40types%2Fturndown\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[\"$L2d\",\"$undefined\"]}],\"@types/turndown\"]}],\"$L2e\"]}],\"$L2f\",\"$L30\",\"$L31\"]}]}]]}]\n"])</script><script>self.__next_f.push([1,"2d:[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}]\n2e:[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^5.0.6\"}]\n2f:[\"$\",\"$L5\",\"tsx\",{\"href\":\"/package/tsx\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"tsx\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^4.0.0\"}]]}]\n30:[\"$\",\"$L5\",\"typescript\",{\"href\":\"/package/typescript\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"typescript\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^5.0.0\"}]]}]\n31:[\"$\",\"$L5\",\"vitest\",{\"href\":\"/package/vitest\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"vitest\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^2.0.0\"}]]}]\n"])</script><div hidden id="S:3"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-dependencies" hidden="" id="radix-_R_aav5ubrb_-content-dependencies" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS=function(a,b){a=document.getElementById(a);b=document.getElementById(b);for(a.parentNode.removeChild(a);a.firstChild;)b.parentNode.insertBefore(a.firstChild,b);b.parentNode.removeChild(b)};$RS("S:3","P:3")</script><div hidden id="S:4"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-versions" hidden="" id="radix-_R_aav5ubrb_-content-versions" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS("S:4","P:4")</script><script>$RC("B:1","S:1")</script></body></html>