AgentSkillsCN

backlog-cli

Nulab 提供的 Backlog 项目管理 CLI 工具。适用于以下场景： (1) 列举、创建、编辑、关闭或评论问题； (2) 创建、列举、合并或评论拉取请求； (3) 查看、创建或编辑 Wiki 页面； (4) 查询项目设置（问题类型、状态、类别、里程碑、成员）； (5) 查看通知、星标或关注情况； (6) 通过 `backlog api` 发送原始 API 请求。

SKILL.md
--- frontmatter
name: backlog-cli
description: |
  CLI for Backlog project management (by Nulab). Use this skill when:
  (1) Listing, creating, editing, closing, or commenting on issues
  (2) Creating, listing, merging, or commenting on pull requests
  (3) Viewing, creating, or editing Wiki pages
  (4) Querying project settings (issue types, statuses, categories, milestones, members)
  (5) Checking notifications, stars, or watches
  (6) Making raw API requests via `backlog api`

backlog-cli

CLI tool for managing Backlog projects via the backlog command.

Authentication

Run backlog auth login before use. Verify with backlog auth status. Switch between spaces with --space <hostname> or BACKLOG_SPACE env var.

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-type 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

Specify with --project (-p) flag or BACKLOG_PROJECT env var.

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
# Set project for session
export BACKLOG_PROJECT=MYAPP

# Now -p flag can be omitted
backlog issue list
backlog milestone list

# CLI flag overrides environment variable
backlog issue list -p OTHER_PROJECT

JSON Output

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
# 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
backlog issue list -p PROJ --json issueKey,summary | jq '.[].summary'

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

Common Workflows

Issues

bash
# 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)
backlog issue create -p PROJ -t "Title" -T "タスク" -P "中" -a @me -d "Description"

# Update status with comment
backlog issue edit PROJ-123 -S "処理中" -c "Starting work"

# Close
backlog issue close PROJ-123 -c "Done"

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

Pull Requests

bash
# Create (required: -p, -R, -t, -B, --branch)
backlog pr create -p PROJ -R repo -t "PR title" -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

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

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"

Raw 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"

Common Issues

Authentication Failed

If you encounter authentication errors:

bash
# Check current authentication status
backlog auth status

# Re-authenticate
backlog auth login

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

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

bash
# Get available statuses for a project
backlog status-type 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)

Before creating or editing issues:

  1. •Query status names: backlog status-type list -p PROJECT
  2. •Query issue types: backlog issue-type list -p PROJECT
  3. •Use exact names from the query results

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

Project Not Found

Ensure the project key is correct and you have access:

bash
# List available projects
backlog project list

# Use exact project key from the list

References