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 (
@merefers to the authenticated user)
Status and issue type names are project-specific. Query them first if unknown:
backlog issue-type list -p PROJECT_KEY
backlog status list -p PROJECT_KEYIssue 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 (requiresBACKLOG_SPACE)
Priority order: CLI flag > Environment variable > Config file (~/.backlogrc)
# 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_PROJECTJSON 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
jqfor advanced filtering:
# 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
# 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
# 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 42Project Info
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 milestonesWiki
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.
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:
# 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:
# 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)Before creating or editing issues:
- Query status names:
backlog status list -p PROJECT - Query issue types:
backlog issue-type list -p PROJECT - 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:
# List available projects
backlog project list
# Use exact project key from the listReferences
- Full command options: references/commands.md
- Data model schemas: references/schema.md