basecamp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/basecamp - Basecamp Workflow Command

/basecamp - Basecamp 工作流命令

Full CLI coverage: 130 endpoints across todos, cards, messages, files, schedule, check-ins, timeline, recordings, templates, webhooks, subscriptions, lineup, and campfire.

完整 CLI 覆盖：130个接口，涵盖待办事项、卡片、消息、文件、日程、签到、时间线、记录、模板、webhooks、订阅、全局里程碑、篝火聊天等功能。

Agent Invariants

Agent 固定规则

MUST follow these rules:

Always use
--json
for structured, predictable output
Parse URLs first with
```
basecamp url parse "<url>"
```
to extract IDs
Comments are flat - reply to parent recording, not to comments
Check context via
```
.basecamp/config.json
```
before assuming project
Rich text fields accept Markdown - the CLI converts to HTML automatically
Project scope is mandatory — via
```
--in <project>
```
or
```
.basecamp/config.json
```
. There is no cross-project query mode. For cross-project data, use
```
basecamp recordings <type>
```
or loop through projects individually.

必须遵守以下规则：

始终使用
--json
以获得结构化、可预测的输出
优先解析URL，通过
```
basecamp url parse "<url>"
```
提取ID
评论为扁平结构，直接回复父级记录即可，无需回复具体评论
在假设项目归属前，先通过
```
.basecamp/config.json
```
检查上下文
富文本字段支持 Markdown，CLI 会自动转换为 HTML
必须指定项目范围——可通过
```
--in <project>
```
或
```
.basecamp/config.json
```
指定。不存在跨项目查询模式，如需获取跨项目数据，请使用
```
basecamp recordings <type>
```
或逐个遍历项目。

Output Modes

输出模式

bash

basecamp <cmd> --json      # JSON envelope with data, summary, breadcrumbs (recommended)
basecamp <cmd> --quiet     # Raw JSON data only, no envelope
basecamp <cmd> --agent     # Machine-readable, no interactive prompts
basecamp <cmd> --ids-only  # Just IDs, one per line
basecamp <cmd> --count     # Just the count
basecamp <cmd> --stats     # Include session stats in output

bash

basecamp <cmd> --json      # 带数据、摘要、路径的JSON封装格式（推荐）
basecamp <cmd> --quiet     # 仅返回原始JSON数据，无封装
basecamp <cmd> --agent     # 机器可读格式，无交互式提示
basecamp <cmd> --ids-only  # 仅返回ID，每行一个
basecamp <cmd> --count     # 仅返回数量
basecamp <cmd> --stats     # 输出包含会话统计信息

Pagination

分页

bash

basecamp <cmd> --limit 50   # Cap results (default varies by resource)
basecamp <cmd> --all        # Fetch all (may be slow for large datasets)
basecamp <cmd> --page 1     # First page only, no auto-pagination

--all

and

--limit

are mutually exclusive.

--page

cannot combine with either.

bash

basecamp <cmd> --limit 50   # 限制结果数量（默认值因资源类型而异）
basecamp <cmd> --all        # 获取全部结果（大数据集可能较慢）
basecamp <cmd> --page 1     # 仅返回第一页，不自动分页

--all

和

--limit

互斥，

--page

不能和两者同时使用。

Smart Defaults

智能默认值

```
--assignee me
```
resolves to current user
```
--due tomorrow
```
/
```
--due +3
```
/
```
--due "next week"
```
- natural date parsing
Project from
```
.basecamp/config.json
```
if
```
--in
```
not specified

```
--assignee me
```
会自动解析为当前用户
```
--due tomorrow
```
/
```
--due +3
```
/
```
--due "next week"
```
- 支持自然语言日期解析
未指定
```
--in
```
时，自动从
```
.basecamp/config.json
```
读取项目配置

Quick Reference

快速参考

Note: Most queries require project scope (via
--in <project>
or
.basecamp/config.json
). For cross-project data, use
basecamp recordings <type>
or loop through projects individually.

Task	Command
List projects	`basecamp projects --json`
My todos (in project)	`basecamp todos --assignee me --in <project> --json`
All todos (cross-project)	`basecamp recordings todos --json` (filter client-side)
Overdue todos	`basecamp todos --overdue --in <project> --json`
Create todo	`basecamp todo --content "Task" --in <project> --list <list> --json`
Create todolist	`basecamp todolists create --name "Name" --in <project> --json`
Complete todo	`basecamp done <id> --json`
List cards	`basecamp cards --in <project> --json`
Create card	`basecamp card --title "Title" --in <project> --json`
Move card	`basecamp cards move <id> --to <column> --in <project> --json`
Post message	`basecamp message --subject "Title" --content "Body" --in <project> --json`
Post to campfire	`basecamp campfire post --content "Message" --in <project> --json`
Add comment	`basecamp comment --content "Text" --on <recording_id> --in <project> --json`
Search	`basecamp search "query" --json`
Parse URL	`basecamp url parse "<url>" --json`
Download file	`basecamp files download <id> --in <project>`
Watch timeline	`basecamp timeline --watch`

注意： 大多数查询需要指定项目范围（通过
--in <project>
或
.basecamp/config.json
）。如需跨项目数据，请使用
basecamp recordings <type>
或逐个遍历项目。

任务	命令
列出项目	`basecamp projects --json`
我的待办（指定项目内）	`basecamp todos --assignee me --in <project> --json`
所有待办（跨项目）	`basecamp recordings todos --json` （客户端过滤）
逾期待办	`basecamp todos --overdue --in <project> --json`
创建待办	`basecamp todo --content "Task" --in <project> --list <list> --json`
创建待办列表	`basecamp todolists create --name "Name" --in <project> --json`
完成待办	`basecamp done <id> --json`
列出卡片	`basecamp cards --in <project> --json`
创建卡片	`basecamp card --title "Title" --in <project> --json`
移动卡片	`basecamp cards move <id> --to <column> --in <project> --json`
发布消息	`basecamp message --subject "Title" --content "Body" --in <project> --json`
发送篝火聊天消息	`basecamp campfire post --content "Message" --in <project> --json`
添加评论	`basecamp comment --content "Text" --on <recording_id> --in <project> --json`
搜索	`basecamp search "query" --json`
解析URL	`basecamp url parse "<url>" --json`
下载文件	`basecamp files download <id> --in <project>`
监控时间线	`basecamp timeline --watch`

URL Parsing

URL 解析

Always parse URLs before acting on them:

bash

basecamp url parse "https://3.basecamp.com/2914079/buckets/41746046/messages/9478142982#__recording_9488783598" --json

Returns:

account_id

project_id

type

recording_id

comment_id

(from fragment).

URL patterns:

```
/buckets/27/messages/123
```
- Message 123 in project 27

/buckets/27/messages/123#__recording_456

- Comment 456 on message 123

```
/buckets/27/card_tables/cards/789
```
- Card 789
```
/buckets/27/card_tables/columns/456
```
- Column 456 (for creating cards)
```
/buckets/27/todos/101
```
- Todo 101
```
/buckets/27/uploads/202
```
- Upload/file 202
```
/buckets/27/documents/303
```
- Document 303
```
/buckets/27/schedule_entries/404
```
- Schedule entry 404

Replying to comments:

bash

undefined

操作前务必先解析URL：

bash

basecamp url parse "https://3.basecamp.com/2914079/buckets/41746046/messages/9478142982#__recording_9488783598" --json

返回值：

account_id

、

project_id

、

type

、

recording_id

、

comment_id

（从片段中提取）。

URL 模式：

```
/buckets/27/messages/123
```
- 项目27中的消息123

/buckets/27/messages/123#__recording_456

- 消息123下的评论456

```
/buckets/27/card_tables/cards/789
```
- 卡片789
```
/buckets/27/card_tables/columns/456
```
- 列456（用于创建卡片）
```
/buckets/27/todos/101
```
- 待办101
```
/buckets/27/uploads/202
```
- 上传/文件202
```
/buckets/27/documents/303
```
- 文档303
```
/buckets/27/schedule_entries/404
```
- 日程条目404

回复评论：

bash

undefined

Comments are flat - reply to the parent recording_id, not the comment_id

评论为扁平结构，回复父级recording_id即可，无需回复comment_id

basecamp url parse "https://...messages/123#__recording_456" --json

Returns recording_id: 123 (parent), comment_id: 456 (fragment) - comment on 123, not 456

返回 recording_id: 123（父级）, comment_id: 456（片段）- 评论到123即可，不需要回复456

basecamp comment --content "Reply" --on 123 --in <project>

undefined

basecamp comment --content "Reply" --on 123 --in <project>

undefined

Decision Trees

决策树

Finding Content

查找内容

Need to find something?
├── Know the type + project? → basecamp <type> --in <project> --json
├── Need cross-project data? → basecamp recordings <type> --json (ONLY cross-project option)
│   (types: todos, messages, documents, comments, cards, uploads)
│   Note: Defaults to active status; use --status archived for archived items
├── Full-text search? → basecamp search "query" --json
└── Have a URL? → basecamp url parse "<url>" --json

需要查找内容？
├── 知道类型+所属项目？ → basecamp <type> --in <project> --json
├── 需要跨项目数据？ → basecamp recordings <type> --json（唯一的跨项目查询方式）
│   可选类型: todos, messages, documents, comments, cards, uploads
│   注意：默认返回活跃状态内容，查询已归档内容请使用 --status archived
├── 需要全文搜索？ → basecamp search "query" --json
└── 已有URL？ → basecamp url parse "<url>" --json

Modifying Content

修改内容

Want to change something?
├── Have URL? → basecamp url parse "<url>" → use extracted IDs
├── Have ID? → basecamp <resource> update <id> --field value
├── Change status? → basecamp recordings trash|archive|restore <id>
└── Complete todo? → basecamp done <id>

需要修改内容？
├── 已有URL？ → basecamp url parse "<url>" → 使用提取到的ID
├── 已有ID？ → basecamp <resource> update <id> --field value
├── 修改状态？ → basecamp recordings trash|archive|restore <id>
└── 完成待办？ → basecamp done <id>

Common Workflows

常见工作流

Link Code to Basecamp Todo

将代码关联到Basecamp待办

bash

undefined

bash

undefined

Get commit info and comment on todo (use printf %q for safe quoting)

获取提交信息并评论到待办（使用printf %q实现安全转义）

COMMIT=$(git rev-parse --short HEAD) MSG=$(git log -1 --format=%s) basecamp comment --content "Commit $COMMIT: $(printf '%s' "$MSG")" --on <todo_id> --in <project>

Complete when done

完成后标记待办为已完成

basecamp done <todo_id>

undefined

basecamp done <todo_id>

undefined

Track PR in Basecamp

在Basecamp中跟踪PR

bash

undefined

bash

undefined

Create todo for PR work

为PR评审创建待办

basecamp todo --content "Review PR #42" --in <project> --assignee me --due tomorrow

When merged

合并后处理

basecamp done <todo_id> basecamp campfire post --content "Merged PR #42" --in <project>

undefined

basecamp done <todo_id> basecamp campfire post --content "Merged PR #42" --in <project>

undefined

Bulk Process Overdue Todos

批量处理逾期待办

bash

undefined

bash

undefined

Preview overdue todos

预览逾期待办

basecamp todos sweep --overdue --dry-run --in <project>

Complete all with comment

全部标记为完成并添加评论

basecamp todos sweep --overdue --complete --comment "Cleaning up" --in <project>

undefined

basecamp todos sweep --overdue --complete --comment "Cleaning up" --in <project>

undefined

Move Card Through Workflow

流转看板卡片

bash

undefined

bash

undefined

List columns to get IDs

列出列获取ID

basecamp cards columns --in <project> --json

Move card to column

移动卡片到指定列

basecamp cards move <card_id> --to <column_id> --in <project>

undefined

basecamp cards move <card_id> --to <column_id> --in <project>

undefined

Download File from Basecamp

从Basecamp下载文件

bash

basecamp files download <upload_id> --in <project> --out ./downloads

bash

basecamp files download <upload_id> --in <project> --out ./downloads

Resource Reference

资源参考

Projects

项目

bash

basecamp projects --json                          # List all
basecamp projects show <id> --json                # Show details
basecamp projects create --name "Name" --json     # Create
basecamp projects update <id> --name "New"        # Update

bash

basecamp projects --json                          # 列出所有项目
basecamp projects show <id> --json                # 查看详情
basecamp projects create --name "Name" --json     # 创建项目
basecamp projects update <id> --name "New"        # 更新项目

Todos

待办事项

bash

basecamp todos --in <project> --json              # List in project
basecamp todos --assignee me --in <project>       # My todos
basecamp todos --overdue --in <project>           # Overdue only
basecamp todos --status completed --in <project>  # Completed
basecamp todos --list <todolist_id> --in <project> # In specific list
basecamp todo --content "Task" --in <project> --list <list> --assignee me --due tomorrow
basecamp done <id> [id...]                        # Complete (multiple OK)
basecamp reopen <id>                              # Uncomplete
basecamp todos position <id> --to 1               # Move to top
basecamp todos sweep --overdue --complete --comment "Done" --in <project>

Flags:

--assignee

(todos only - not available on cards/messages),

--status

(completed/pending),

--overdue

--list

--due

--limit

--all

bash

basecamp todos --in <project> --json              # 列出项目内待办
basecamp todos --assignee me --in <project>       # 我的待办
basecamp todos --overdue --in <project>           # 仅逾期待办
basecamp todos --status completed --in <project>  # 已完成待办
basecamp todos --list <todolist_id> --in <project> # 指定待办列表下的待办
basecamp todo --content "Task" --in <project> --list <list> --assignee me --due tomorrow
basecamp done <id> [id...]                        # 标记完成（支持批量）
basecamp reopen <id>                              # 重新打开
basecamp todos position <id> --to 1               # 移动到顶部
basecamp todos sweep --overdue --complete --comment "Done" --in <project>

参数：

--assignee

（仅待办支持，卡片/消息不支持）、

--status

（completed/pending）、

--overdue

、

--list

、

--due

、

--limit

、

--all

Todolists

待办列表

Todolists are containers for todos. Create a todolist before adding todos.

bash

basecamp todolists --in <project> --json                          # List todolists
basecamp todolists show <id> --in <project>                       # Show details
basecamp todolists create --name "Name" --in <project> --json     # Create
basecamp todolists create --name "Name" --description "Desc" --in <project>
basecamp todolists update <id> --name "New" --in <project>        # Update

待办列表是待办事项的容器，添加待办前需要先创建待办列表。

bash

basecamp todolists --in <project> --json                          # 列出待办列表
basecamp todolists show <id> --in <project>                       # 查看详情
basecamp todolists create --name "Name" --in <project> --json     # 创建待办列表
basecamp todolists create --name "Name" --description "Desc" --in <project>
basecamp todolists update <id> --name "New" --in <project>        # 更新待办列表

Cards (Kanban)

卡片（看板）

Note: Cards do NOT support

--assignee

filtering like todos. Fetch all cards and filter client-side if needed. If a project has multiple card tables, you must specify

--card-table <id>

. When you get an "Ambiguous card table" error, the hint shows available table IDs and names.

bash

basecamp cards --in <project> --json              # All cards
basecamp cards --card-table <id> --in <project>   # Cards from specific table (required if multiple)
basecamp cards --column <id> --in <project>       # Cards in column
basecamp cards columns --in <project> --json      # List columns (needs --card-table if multiple)
basecamp cards show <id> --in <project>           # Card details
basecamp card --title "Title" --content "<p>Body</p>" --in <project> --column <id>
basecamp cards update <id> --title "New" --due tomorrow --assignee me
basecamp cards move <id> --to <column_id>         # Move to column (numeric ID)
basecamp cards move <id> --to "Done" --card-table <table_id>  # Move by name (needs table)

Identifying completed cards: Cards in Done columns have

parent.type: "Kanban::DoneColumn"

and

completed: true

. Use this to identify completed cards that haven't been archived.

Limitation: Basecamp does not track when cards are moved between columns. The

updated_at

field updates on any modification and cannot reliably indicate when a card was completed.

Card Steps (checklists):

bash

basecamp cards steps <card_id> --in <project>     # List steps
basecamp cards step create --title "Step" --card <id> --in <project>
basecamp cards step complete <step_id> --in <project>
basecamp cards step uncomplete <step_id>

Column management:

bash

basecamp cards column show <id> --in <project>
basecamp cards column create --title "Name" --in <project>
basecamp cards column update <id> --title "New"
basecamp cards column move <id> --position 2
basecamp cards column color <id> --color blue
basecamp cards column on-hold <id>                # Enable on-hold section
basecamp cards column watch <id>                  # Subscribe to column

注意： 卡片不支持待办那样的

--assignee

过滤，如有需要请拉取全部卡片后在客户端过滤。如果项目有多个看板，必须指定

--card-table <id>

。出现「Ambiguous card table」错误时，提示信息会展示可用的看板ID和名称。

bash

basecamp cards --in <project> --json              # 所有卡片
basecamp cards --card-table <id> --in <project>   # 指定看板下的卡片（多个看板时必填）
basecamp cards --column <id> --in <project>       # 指定列下的卡片
basecamp cards columns --in <project> --json      # 列出列（多个看板时需要--card-table参数）
basecamp cards show <id> --in <project>           # 卡片详情
basecamp card --title "Title" --content "<p>Body</p>" --in <project> --column <id>
basecamp cards update <id> --title "New" --due tomorrow --assignee me
basecamp cards move <id> --to <column_id>         # 移动到指定列（数字ID）
basecamp cards move <id> --to "Done" --card-table <table_id>  # 按列名移动（需要指定看板）

识别已完成卡片： 完成列中的卡片带有

parent.type: "Kanban::DoneColumn"

和

completed: true

标识，可以用来识别未归档的已完成卡片。

限制： Basecamp 不跟踪卡片在列之间的移动时间，

updated_at

字段会在任何修改时更新，无法可靠标识卡片完成时间。

卡片步骤（检查清单）：

bash

basecamp cards steps <card_id> --in <project>     # 列出步骤
basecamp cards step create --title "Step" --card <id> --in <project>
basecamp cards step complete <step_id> --in <project>
basecamp cards step uncomplete <step_id>

列管理：

bash

basecamp cards column show <id> --in <project>
basecamp cards column create --title "Name" --in <project>
basecamp cards column update <id> --title "New"
basecamp cards column move <id> --position 2
basecamp cards column color <id> --color blue
basecamp cards column on-hold <id>                # 启用待处理区域
basecamp cards column watch <id>                  # 订阅列变更

Messages

消息

bash

basecamp messages --in <project> --json           # List messages
basecamp messages show <id> --in <project>        # Show message
basecamp message --subject "Title" --content "Body" --in <project>
basecamp messages update <id> --subject "New" --content "Updated"
basecamp messages pin <id> --in <project>         # Pin to top
basecamp messages unpin <id>                      # Unpin

Flags:

--draft

(create as draft),

--message-board <id>

(if multiple boards)

bash

basecamp messages --in <project> --json           # 列出消息
basecamp messages show <id> --in <project>        # 查看消息详情
basecamp message --subject "Title" --content "Body" --in <project>
basecamp messages update <id> --subject "New" --content "Updated"
basecamp messages pin <id> --in <project>         # 置顶
basecamp messages unpin <id>                      # 取消置顶

参数：

--draft

（存为草稿）、

--message-board <id>

（多个留言板时指定）

Comments

bash

basecamp comments --on <recording_id> --in <project> --json
basecamp comment --content "Text" --on <recording_id> --in <project>
basecamp comments update <id> --content "Updated" --in <project>

bash

basecamp comments --on <recording_id> --in <project> --json
basecamp comment --content "Text" --on <recording_id> --in <project>
basecamp comments update <id> --content "Updated" --in <project>

Files & Documents

文件与文档

bash

basecamp files --in <project> --json              # List all (folders, files, docs)
basecamp files --vault <folder_id> --in <project> # List folder contents
basecamp files show <id> --in <project>           # Show item (auto-detects type)
basecamp files download <id> --in <project>       # Download file
basecamp files download <id> --out ./dir          # Download to specific dir
basecamp files folder create --name "Folder" --in <project>
basecamp files doc create --title "Doc" --content "Body" --in <project>
basecamp files doc create --title "Draft" --draft --in <project>
basecamp files update <id> --title "New" --content "Updated"

Subcommands:

folders

uploads

documents

(each with pagination flags)

bash

basecamp files --in <project> --json              # 列出所有内容（文件夹、文件、文档）
basecamp files --vault <folder_id> --in <project> # 列出文件夹内容
basecamp files show <id> --in <project>           # 查看条目详情（自动识别类型）
basecamp files download <id> --in <project>       # 下载文件
basecamp files download <id> --out ./dir          # 下载到指定目录
basecamp files folder create --name "Folder" --in <project>
basecamp files doc create --title "Doc" --content "Body" --in <project>
basecamp files doc create --title "Draft" --draft --in <project>
basecamp files update <id> --title "New" --content "Updated"

子命令：

folders

、

uploads

、

documents

（均支持分页参数）

Schedule

日程

bash

basecamp schedule --in <project> --json           # Schedule info
basecamp schedule entries --in <project> --json   # List entries
basecamp schedule show <id> --in <project>        # Entry details
basecamp schedule show <id> --date 20240315       # Specific occurrence (recurring)
basecamp schedule create "Event" --starts-at "2024-03-15T09:00:00Z" --ends-at "2024-03-15T10:00:00Z" --in <project>
basecamp schedule create "Meeting" --all-day --notify --participants 1,2,3 --in <project>
basecamp schedule update <id> --summary "New title" --starts-at "..."
basecamp schedule settings --include-due --in <project>  # Include todos/cards due dates

Flags:

--all-day

--notify

--participants <ids>

--status

(active/archived/trashed)

bash

basecamp schedule --in <project> --json           # 日程信息
basecamp schedule entries --in <project> --json   # 列出日程条目
basecamp schedule show <id> --in <project>        # 条目详情
basecamp schedule show <id> --date 20240315       # 指定重复日程的具体场次
basecamp schedule create "Event" --starts-at "2024-03-15T09:00:00Z" --ends-at "2024-03-15T10:00:00Z" --in <project>
basecamp schedule create "Meeting" --all-day --notify --participants 1,2,3 --in <project>
basecamp schedule update <id> --summary "New title" --starts-at "..."
basecamp schedule settings --include-due --in <project>  # 包含待办/卡片截止日期

参数：

--all-day

、

--notify

、

--participants <ids>

、

--status

（active/archived/trashed）

Check-ins

签到

bash

basecamp checkins --in <project> --json           # Questionnaire info
basecamp checkins questions --in <project>        # List questions
basecamp checkins question <id> --in <project>    # Question details
basecamp checkins answers <question_id> --in <project>  # List answers
basecamp checkins answer <id> --in <project>      # Answer details
basecamp checkins question create --title "What did you work on?" --in <project>
basecamp checkins question update <id> --title "New question" --frequency every_week
basecamp checkins answer create --question <id> --content "My answer" --in <project>
basecamp checkins answer update <id> --content "Updated" --in <project>

Schedule options:

--frequency

(every_day, every_week, every_other_week, every_month, on_certain_days),

--days 1,2,3,4,5

(0=Sun),

--time "5:00pm"

bash

basecamp checkins --in <project> --json           # 问卷信息
basecamp checkins questions --in <project>        # 列出问题
basecamp checkins question <id> --in <project>    # 问题详情
basecamp checkins answers <question_id> --in <project>  # 列出回答
basecamp checkins answer <id> --in <project>      # 回答详情
basecamp checkins question create --title "What did you work on?" --in <project>
basecamp checkins question update <id> --title "New question" --frequency every_week
basecamp checkins answer create --question <id> --content "My answer" --in <project>
basecamp checkins answer update <id> --content "Updated" --in <project>

日程选项：

--frequency

（every_day、every_week、every_other_week、every_month、on_certain_days）、

--days 1,2,3,4,5

（0=周日）、

--time "5:00pm"

Timeline

时间线

bash

basecamp timeline --json                          # Account-wide activity
basecamp timeline --in <project> --json           # Project activity
basecamp timeline me --json                       # Your activity
basecamp timeline --person <id> --json            # Person's activity
basecamp timeline --watch                         # Live monitoring (TUI)
basecamp timeline --watch --interval 60           # Poll every 60 seconds

Note:

basecamp timeline

(account-wide) works reliably. The

--limit

flag is not supported on timeline commands.

bash

basecamp timeline --json                          # 账号级活动记录
basecamp timeline --in <project> --json           # 项目级活动记录
basecamp timeline me --json                       # 你的活动记录
basecamp timeline --person <id> --json            # 指定用户的活动记录
basecamp timeline --watch                         # 实时监控（终端交互界面）
basecamp timeline --watch --interval 60           # 每60秒轮询一次

注意：

basecamp timeline

（账号级）运行稳定，时间线命令不支持

--limit

参数。

Recordings (Cross-project)

记录（跨项目）

Use

basecamp recordings <type>

for cross-project queries - this is the only way to query across all projects in one call.

bash

basecamp recordings todos --json                  # All todos across projects
basecamp recordings todos --all --json            # All todos (paginate through all)
basecamp recordings messages --in <project>       # Messages in project
basecamp recordings documents --status archived   # Archived docs
basecamp recordings cards --sort created_at --direction asc
basecamp recordings cards --status archived --all --json  # Include archived cards

Types:

todos

messages

documents

comments

cards

uploads

Status filtering: By default, only

active

recordings are returned. Use

--status archived

--status trashed

to query other statuses. You may need separate queries to get complete data (e.g., active + archived).

Status management:

bash

basecamp recordings trash <id> --in <project>     # Move to trash
basecamp recordings archive <id> --in <project>   # Archive
basecamp recordings restore <id> --in <project>   # Restore to active
basecamp recordings visibility <id> --visible --in <project>  # Show to clients
basecamp recordings visibility <id> --hidden      # Hide from clients

使用

basecamp recordings <type>

进行跨项目查询，这是唯一支持单次调用查询所有项目的方式。

bash

basecamp recordings todos --json                  # 跨项目所有待办
basecamp recordings todos --all --json            # 所有待办（全量分页拉取）
basecamp recordings messages --in <project>       # 项目内消息
basecamp recordings documents --status archived   # 已归档文档
basecamp recordings cards --sort created_at --direction asc
basecamp recordings cards --status archived --all --json  # 包含已归档卡片

可选类型：

todos

、

messages

、

documents

、

comments

、

cards

、

uploads

状态过滤： 默认仅返回

active

状态的记录，使用

--status archived

或

--status trashed

查询其他状态的内容，可能需要多次查询才能获取完整数据（例如活跃+归档）。

状态管理：

bash

basecamp recordings trash <id> --in <project>     # 移到回收站
basecamp recordings archive <id> --in <project>   # 归档
basecamp recordings restore <id> --in <project>   # 恢复为活跃状态
basecamp recordings visibility <id> --visible --in <project>  # 对客户可见
basecamp recordings visibility <id> --hidden      # 对客户隐藏

Templates

模板

bash

basecamp templates --json                         # List templates
basecamp templates show <id> --json               # Template details
basecamp templates create "Template Name"         # Create empty template
basecamp templates update <id> --name "New Name"
basecamp templates delete <id>                    # Trash template
basecamp templates construct <id> --name "New Project"  # Create project (async)
basecamp templates construction <template_id> <construction_id>  # Check status

Construct returns construction_id - poll until status="completed" to get project.

bash

basecamp templates --json                         # 列出模板
basecamp templates show <id> --json               # 模板详情
basecamp templates create "Template Name"         # 创建空模板
basecamp templates update <id> --name "New Name"
basecamp templates delete <id>                    # 删除模板
 basecamp templates construct <id> --name "New Project"  # 创建项目（异步）
basecamp templates construction <template_id> <construction_id>  # 检查创建状态

创建命令会返回construction_id，请轮询直到status="completed"获取项目ID。

Webhooks

bash

basecamp webhooks --in <project> --json           # List webhooks
basecamp webhooks show <id> --in <project>        # Webhook details
basecamp webhooks create --url "https://..." --in <project>
basecamp webhooks create --url "https://..." --types "Todo,Comment" --in <project>
basecamp webhooks update <id> --active --in <project>
basecamp webhooks update <id> --inactive          # Disable
basecamp webhooks delete <id> --in <project>

Event types: Todo, Todolist, Message, Comment, Document, Upload, Vault, Schedule::Entry, Kanban::Card, Question, Question::Answer

bash

basecamp webhooks --in <project> --json           # 列出webhooks
basecamp webhooks show <id> --in <project>        # webhook详情
basecamp webhooks create --url "https://..." --in <project>
basecamp webhooks create --url "https://..." --types "Todo,Comment" --in <project>
basecamp webhooks update <id> --active --in <project>
basecamp webhooks update <id> --inactive          # 禁用
basecamp webhooks delete <id> --in <project>

事件类型： Todo、Todolist、Message、Comment、Document、Upload、Vault、Schedule::Entry、Kanban::Card、Question、Question::Answer

Subscriptions

basecamp subscriptions <recording_id> --in <project>  # Who's subscribed
basecamp subscriptions subscribe <id> --in <project>  # Subscribe yourself
basecamp subscriptions unsubscribe <id>               # Unsubscribe
basecamp subscriptions add <id> --people 1,2,3        # Add people
basecamp subscriptions remove <id> --people 1,2,3     # Remove people

bash

basecamp subscriptions <recording_id> --in <project>  # 查看订阅者列表
basecamp subscriptions subscribe <id> --in <project>  # 订阅自己
basecamp subscriptions unsubscribe <id>               # 取消订阅
basecamp subscriptions add <id> --people 1,2,3        # 添加订阅者
basecamp subscriptions remove <id> --people 1,2,3     # 移除订阅者

Lineup (Account-wide Markers)

全局里程碑（Lineup）

bash

basecamp lineup create "Milestone" "2024-03-15"   # Create marker
basecamp lineup create --name "Launch" --date tomorrow
basecamp lineup update <id> --name "New Name" --date "+7"
basecamp lineup delete <id>

Note: Lineup markers are account-wide, not project-scoped.

bash

basecamp lineup create "Milestone" "2024-03-15"   # 创建里程碑
basecamp lineup create --name "Launch" --date tomorrow
basecamp lineup update <id> --name "New Name" --date "+7"
basecamp lineup delete <id>

注意： 全局里程碑是账号级的，不属于具体项目。

Campfire

篝火聊天

bash

basecamp campfire --in <project> --json           # List campfires
basecamp campfire messages --in <project> --json  # List messages
basecamp campfire post --content "Hello!" --in <project>
basecamp campfire line <line_id> --in <project>   # Show line
basecamp campfire delete <line_id> --in <project> # Delete line

bash

basecamp campfire --in <project> --json           # 列出聊天频道
basecamp campfire messages --in <project> --json  # 列出消息
basecamp campfire post --content "Hello!" --in <project>
basecamp campfire line <line_id> --in <project>   # 查看消息详情
basecamp campfire delete <line_id> --in <project> # 删除消息

People

用户

bash

basecamp people --json                            # All people in account
basecamp people --in <project> --json             # People on project
basecamp me --json                                # Current user
basecamp people show <id> --json                  # Person details
basecamp people add <id> --in <project>           # Add to project
basecamp people remove <id> --in <project>        # Remove from project

bash

basecamp people --json                            # 账号内所有用户
basecamp people --in <project> --json             # 项目内用户
basecamp me --json                                # 当前用户信息
basecamp people show <id> --json                  # 用户详情
basecamp people add <id> --in <project>           # 添加用户到项目
basecamp people remove <id> --in <project>        # 从项目移除用户

Search

搜索

bash

basecamp search "query" --json                    # Full-text search
basecamp search "query" --sort updated_at --limit 20
basecamp search metadata --json                   # Available search scopes

bash

basecamp search "query" --json                    # 全文搜索
basecamp search "query" --sort updated_at --limit 20
basecamp search metadata --json                   # 可用搜索范围

Generic Show

通用查询

bash

basecamp show <type> <id> --in <project> --json   # Show any recording type

bash

basecamp show <type> <id> --in <project> --json   # 查看任意类型的记录

Types: todo, todolist, message, comment, card, card-table, document (or omit <type> for generic lookup)

可选类型: todo, todolist, message, comment, card, card-table, document（也可省略<type>进行通用查询）

undefined

undefined

Configuration

配置

The CLI uses two directory namespaces:

basecamp

for your Basecamp identity and project relationships,

basecamp

for tool-specific operational data.

~/.config/basecamp/           # Basecamp identity (DO NOT read credentials)
├── credentials.json          #   OAuth tokens — NEVER read or log
├── client.json               #   DCR client registration
└── config.json               #   Global preferences (account_id, base_url, format)

~/.cache/basecamp/            # Tool cache (ephemeral, auto-managed)
├── completion.json           #   Tab completion cache
└── resilience/               #   Circuit breaker state

.basecamp/                    # Per-repo config (committed to git)
└── config.json               #   Project defaults (project_id, account_id, todolist_id)

Per-repo config:

.basecamp/config.json

json

{
  "project_id": "12345",
  "todolist_id": "67890"
}

Initialize:

bash

basecamp config init
basecamp config set project_id <id>
basecamp config set todolist_id <id>

Check context:

bash

cat .basecamp/config.json 2>/dev/null || echo "No project configured"

Global config:

~/.config/basecamp/config.json

(account_id, base_url, format preferences)

CLI 使用两个目录命名空间：

basecamp

存储你的Basecamp身份和项目关联信息，

basecamp

存储工具专属运行数据。

~/.config/basecamp/           # Basecamp身份信息（请勿读取凭证）
├── credentials.json          #   OAuth令牌 —— 绝对不要读取或日志记录
├── client.json               #   DCR客户端注册信息
└── config.json               #   全局偏好配置（account_id、base_url、输出格式）

~/.cache/basecamp/            # 工具缓存（临时数据，自动管理）
├── completion.json           #   自动补全缓存
└── resilience/               #   熔断状态

.basecamp/                    # 仓库级配置（可提交到git）
└── config.json               #   项目默认配置（project_id、account_id、todolist_id）

仓库级配置：

.basecamp/config.json

json

{
  "project_id": "12345",
  "todolist_id": "67890"
}

初始化：

bash

basecamp config init
basecamp config set project_id <id>
basecamp config set todolist_id <id>

检查上下文：

bash

cat .basecamp/config.json 2>/dev/null || echo "No project configured"

全局配置：

~/.config/basecamp/config.json

（account_id、base_url、格式偏好）

Error Handling

错误处理

General diagnostics:

bash

basecamp doctor --json                            # Check CLI health, auth, connectivity

Rate limiting (429): The CLI handles backoff automatically. If you see 429 errors, reduce request frequency.

Authentication errors:

bash

basecamp auth status                              # Check auth
basecamp auth login                               # Re-authenticate (full access)
basecamp auth login --scope read                  # Read-only access

Network errors / localhost URLs:

bash

undefined

通用诊断：

bash

basecamp doctor --json                            # 检查CLI健康状态、认证、连通性

限流（429错误）： CLI 会自动处理退避逻辑，如果出现429错误请降低请求频率。

认证错误：

bash

basecamp auth status                              # 检查认证状态
basecamp auth login                               # 重新认证（全权限）
basecamp auth login --scope read                  # 只读权限认证

网络错误 / localhost URL问题：

bash

undefined

Check for dev config

检查开发配置

cat ~/.config/basecamp/config.json

Should only contain: {"account_id": "<id>"}

应仅包含: {"account_id": "<id>"}

Remove base_url/api_url if pointing to localhost

如果base_url/api_url指向localhost请删除


**Not found errors:**
```bash
basecamp auth status                              # Verify auth working
cat ~/.config/basecamp/accounts.json              # Check available accounts

Invalid flag errors: All shortcut commands require explicit flags:

basecamp todo --content "text"

(not

basecamp todo "text"

)

basecamp card --title "title"

(not

basecamp card "title"

)

URL malformed (curl exit 3): Special characters in content. Use plain text or properly escaped HTML.


**未找到错误：**
```bash
basecamp auth status                              # 确认认证正常
cat ~/.config/basecamp/accounts.json              # 检查可用账号

参数错误： 所有快捷命令都需要显式指定参数：

basecamp todo --content "text"

（不要写

basecamp todo "text"

）

basecamp card --title "title"

（不要写

basecamp card "title"

）

URL格式错误（curl exit 3）： 内容包含特殊字符，请使用纯文本或正确转义的HTML。

Learn More

了解更多

API concepts: https://github.com/basecamp/bc3-api#key-concepts
CLI repo: https://github.com/basecamp/basecamp-cli
API coverage: See API-COVERAGE.md in the CLI repo

API 概念: https://github.com/basecamp/bc3-api#key-concepts
CLI 仓库: https://github.com/basecamp/basecamp-cli
API 覆盖范围: 参考CLI仓库中的API-COVERAGE.md