backlog-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

backlog-cli

CLI tool for managing Backlog projects via the

backlog

command.

通过

backlog

命令管理Backlog项目的CLI工具。

Authentication

身份验证

Run

backlog auth login

before use. Verify with

backlog auth status

. Switch between spaces with

--space <hostname>

BACKLOG_SPACE

env var.

使用前请运行

backlog auth login

。通过

backlog auth status

验证身份。使用

--space <主机名>

或

BACKLOG_SPACE

环境变量在不同空间间切换。

Key Concepts

核心概念

Avoid Interactive Prompts

避免交互式提示

Some commands prompt interactively for missing required fields. Always specify all required flags explicitly to prevent hanging.

部分命令会在缺少必填字段时以交互方式提示输入。请始终显式指定所有必填标志，以避免程序挂起。

Name Resolution

名称解析

The CLI automatically resolves human-readable names to IDs:

Status names → status ID
Issue type names → issue type ID
Priority names (
```
高
```
/
```
中
```
/
```
低
```
) → priority ID
Usernames → user ID (
```
@me
```
refers to the authenticated user)

Status and issue type names are project-specific. Query them first if unknown:

bash

backlog issue-type list -p PROJECT_KEY
backlog status list -p PROJECT_KEY

CLI会自动将人类可读的名称解析为ID：

状态名称 → 状态ID
问题类型名称 → 问题类型ID
优先级名称（
```
高
```
/
```
中
```
/
```
低
```
）→ 优先级ID
用户名 → 用户ID（
```
@me
```
指已验证身份的当前用户）

状态和问题类型名称是项目特定的。如果未知，请先查询：

bash

backlog issue-type list -p PROJECT_KEY
backlog status list -p PROJECT_KEY

Issue Keys

问题键

Format:

PROJECT_KEY-number

(e.g.,

PROJ-123

). Since the key embeds the project,

--project

is not needed for

issue view

issue edit

格式：

PROJECT_KEY-数字

（例如：

PROJ-123

）。由于键中已包含项目信息，在执行

issue view

issue edit

时无需指定

--project

。

Project Key

项目键

Specify with

--project

(

-p

) flag or

BACKLOG_PROJECT

env var.

通过

--project

（

-p

）标志或

BACKLOG_PROJECT

环境变量指定。

Environment Variables

环境变量

Environment variables provide defaults that can be overridden by CLI flags:

```
BACKLOG_SPACE
```
— Default space hostname (e.g.,
```
example.backlog.com
```
)
```
BACKLOG_PROJECT
```
— Default project key (e.g.,
```
MYAPP
```
)
```
BACKLOG_API_KEY
```
— API key for CI/CD environments (requires
```
BACKLOG_SPACE
```
)

Priority order: CLI flag > Environment variable > Config file (

~/.backlogrc

)

bash

undefined

环境变量提供默认值，可通过CLI标志覆盖：

```
BACKLOG_SPACE
```
— 默认空间主机名（例如：
```
example.backlog.com
```
）
```
BACKLOG_PROJECT
```
— 默认项目键（例如：
```
MYAPP
```
）
```
BACKLOG_API_KEY
```
— CI/CD环境使用的API密钥（需要指定
```
BACKLOG_SPACE
```
）

优先级顺序：CLI标志 > 环境变量 > 配置文件（

~/.backlogrc

）

bash

undefined

Set project for session

为当前会话设置项目

export BACKLOG_PROJECT=MYAPP

Now -p flag can be omitted

现在可省略-p标志

backlog issue list backlog milestone list

CLI flag overrides environment variable

CLI标志会覆盖环境变量

backlog issue list -p OTHER_PROJECT

undefined

backlog issue list -p OTHER_PROJECT

undefined

JSON Output

JSON输出

Most commands support

--json

flag for machine-readable output:

```
--json
```
— output all fields in JSON format

--json field1,field2

— output only specified fields (e.g.,

--json issueKey,summary,status

)

Combine with
```
jq
```
for advanced filtering:

bash

undefined

大多数命令支持

--json

标志以生成机器可读的输出：

```
--json
```
— 以JSON格式输出所有字段

--json field1,field2

— 仅输出指定字段（例如：

--json issueKey,summary,status

）

与
```
jq
```
结合使用可实现高级过滤：

bash

undefined

Extract issue keys only

仅提取问题键

backlog issue list -p PROJ --json | jq '.[].issueKey'

Filter by specific status

按特定状态过滤

backlog issue list -p PROJ --json | jq '[.[] | select(.status.name == "処理中")]'

Combine field filtering with jq

结合字段过滤与jq

backlog issue list -p PROJ --json issueKey,summary | jq '.[].summary'


**Always use `--json` in agent workflows** to parse output reliably.

backlog issue list -p PROJ --json issueKey,summary | jq '.[].summary'


**在Agent工作流中请始终使用`--json`**以确保输出可被可靠解析。

Common Workflows

常见工作流

Issues

问题管理

bash

undefined

bash

undefined

List my open issues

查看我的未处理问题

backlog issue list -p PROJ -a @me -S "未対応,処理中"

View details with comments

查看问题详情及评论

backlog issue view PROJ-123 --comments

Create (required: -p, -t, -T, -P)

创建问题（必填：-p, -t, -T, -P）

backlog issue create -p PROJ -t "Title" -T "タスク" -P "中" -a @me -d "Description"

backlog issue create -p PROJ -t "标题" -T "タスク" -P "中" -a @me -d "描述"

Update status with comment

更新状态并添加评论

backlog issue edit PROJ-123 -S "処理中" -c "Starting work"

backlog issue edit PROJ-123 -S "処理中" -c "开始工作"

Close

关闭问题

backlog issue close PROJ-123 -c "Done"

backlog issue close PROJ-123 -c "已完成"

Add comment

添加评论

backlog issue comment PROJ-123 -b "Progress update"

undefined

backlog issue comment PROJ-123 -b "进度更新"

undefined

Pull Requests

拉取请求（PR）

bash

undefined

bash

undefined

Create (required: -p, -R, -t, -B, --branch)

创建拉取请求（必填：-p, -R, -t, -B, --branch）

backlog pr create -p PROJ -R repo -t "PR title" -B main --branch feat/xxx --issue PROJ-123

backlog pr create -p PROJ -R repo -t "PR标题" -B main --branch feat/xxx --issue PROJ-123

List open PRs

查看未合并的拉取请求

backlog pr list -p PROJ -R repo

View with comments

查看拉取请求详情及评论

backlog pr view -p PROJ -R repo 42 --comments

Merge

合并拉取请求

backlog pr merge -p PROJ -R repo 42

undefined

backlog pr merge -p PROJ -R repo 42

undefined

Project Info

项目信息

bash

backlog project list                  # List projects
backlog project users PROJECT_KEY     # List members
backlog category list -p PROJ         # List categories
backlog milestone list -p PROJ        # List milestones

bash

backlog project list                  # 查看项目列表
backlog project users PROJECT_KEY     # 查看项目成员
backlog category list -p PROJ         # 查看分类列表
backlog milestone list -p PROJ        # 查看里程碑列表

Wiki

Wiki管理

bash

backlog wiki list -p PROJ
backlog wiki view <wiki-id>
backlog wiki create -p PROJ -n "Page title" -b "Content"
backlog wiki edit <wiki-id> -b "Updated content"

bash

backlog wiki list -p PROJ
backlog wiki view <wiki-id>
backlog wiki create -p PROJ -n "页面标题" -b "内容"
backlog wiki edit <wiki-id> -b "更新后的内容"

Raw API

原始API调用

For operations not covered by CLI commands. The

/api/v2

prefix can be omitted.

bash

backlog api /issues -X POST -f "projectId=123" -f "summary=New issue"
backlog api /issues --paginate -f "projectId[]=123"

用于CLI命令未覆盖的操作。可省略

/api/v2

前缀。

bash

backlog api /issues -X POST -f "projectId=123" -f "summary=New issue"
backlog api /issues --paginate -f "projectId[]=123"

Common Issues

常见问题

Authentication Failed

身份验证失败

If you encounter authentication errors:

bash

undefined

如果遇到身份验证错误：

bash

undefined

Check current authentication status

检查当前身份验证状态

backlog auth status

Re-authenticate

重新验证身份

backlog auth login

undefined

backlog auth login

undefined

"Status name not found" or "Issue type not found"

"未找到状态名称"或"未找到问题类型"

Status names and issue type names are project-specific. Always query them first:

bash

undefined

状态名称和问题类型名称是项目特定的。请始终先查询：

bash

undefined

Get available statuses for a project

获取项目的可用状态

backlog status list -p PROJECT_KEY

Get available issue types for a project

获取项目的可用问题类型

backlog issue-type list -p PROJECT_KEY

Get available priorities (these are global)

获取可用优先级（这些是全局的）

Built-in values: 高 (High), 中 (Normal), 低 (Low)

内置值：高 (High), 中 (Normal), 低 (Low)


**Before creating or editing issues:**
1. Query status names: `backlog status list -p PROJECT`
2. Query issue types: `backlog issue-type list -p PROJECT`
3. Use exact names from the query results


**在创建或编辑问题前：**
1. 查询状态名称：`backlog status list -p PROJECT`
2. 查询问题类型：`backlog issue-type list -p PROJECT`
3. 使用查询结果中的精确名称

Missing Required Fields

缺少必填字段

If a command hangs or prompts for input:

You're missing a required field
Specify all required flags explicitly (see command help with
```
--help
```
)
Never rely on interactive prompts in agent workflows

如果命令挂起或提示输入：

你遗漏了必填字段
显式指定所有必填标志（使用
```
--help
```
查看命令帮助）
在Agent工作流中切勿依赖交互式提示

Project Not Found

未找到项目

Ensure the project key is correct and you have access:

bash

undefined

确保项目键正确且你拥有访问权限：

bash

undefined

List available projects

查看可用项目列表

backlog project list

Use exact project key from the list

使用列表中的精确项目键

undefined

undefined

References

参考资料

Full command options: references/commands.md
Data model schemas: references/schema.md

完整命令选项：references/commands.md
数据模型架构：references/schema.md