backlog-agent

name	backlog-agent
description	Manage projects on Nulab Backlog — issues, wikis, milestones, Git, sprints for Japan's top PM tool
author	hanabi-jpn
version	1.0.0
tags	["backlog","nulab","project-management","issue-tracking","git","wiki","sprint","japan"]

╔═══════════════════════════════════════════════════╗
║  ┌───────────────────────────────────────────┐    ║
║  │  B A C K L O G   A G E N T               │    ║
║  │     ━━━━━━━━━━━━━━━━━━━━━━                │    ║
║  │  📋 Issues → Wiki → Git → Sprints        │    ║
║  │     Nulab Project Management CLI          │    ║
║  └───────────────────────────────────────────┘    ║
╚═══════════════════════════════════════════════════╝

backlog nulab project-management issue-tracker git-hosting

Command your entire project from the terminal -- create issues, track sprints, update wikis, and manage Git repos on Japan's most trusted project management platform.

---

Overview

Backlog Agent delivers full programmatic control over Nulab Backlog, the project management platform trusted by development teams, agencies, and enterprises across Japan and Asia-Pacific. Backlog uniquely combines issue tracking, wiki documentation, Git/SVN repository hosting, and Gantt chart planning in a single integrated platform -- a combination that has made it the go-to tool for Japanese software teams who need everything in one place without the fragmentation of using Jira plus Confluence plus GitHub plus separate Gantt tools. This skill makes every Backlog operation accessible from your terminal, enabling seamless integration into development workflows, CI/CD pipelines, and automated reporting systems.

The agent covers the complete Backlog feature set through its comprehensive REST API v2: issue lifecycle management with custom fields, statuses, priorities, and resolution tracking; wiki page creation and editing with Markdown and Backlog's native markup support; milestone and version management for release planning; sprint board operations for agile teams; Git repository management including branches, pull requests, and webhooks; file attachment handling; notification configuration; and bulk operations for project-wide changes. The agent understands Backlog's project key convention (e.g., PROJ-123) and translates between human-readable references and internal IDs seamlessly. It also supports cross-project operations for organizations managing multiple simultaneous projects -- a common pattern in Japanese IT consulting firms (SIer) managing client portfolios.

Architecture:

  ┌──────────────────────────────────────────────────────────────┐
  │                     Backlog Agent CLI                         │
  │                                                              │
  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐   │
  │  │  Issues  │ │   Wiki   │ │   Git    │ │    Sprint     │   │
  │  │  Engine  │ │  Manager │ │  Bridge  │ │    Board      │   │
  │  └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬────────┘   │
  │       │            │            │               │            │
  │  ┌────▼────────────▼────────────▼───────────────▼──────────┐ │
  │  │        Project Key Resolver & ID Mapper                 │ │
  │  │     (PROJ-123 ↔ internal IDs, cross-project)            │ │
  │  └──────────────────────┬──────────────────────────────────┘ │
  │                         │                                    │
  │  ┌──────────────────────▼──────────────────────────────────┐ │
  │  │         API Key / OAuth2 Auth Layer                     │ │
  │  │    ({space}.backlog.com or {space}.backlog.jp)           │ │
  │  └──────────────────────┬──────────────────────────────────┘ │
  └─────────────────────────┼────────────────────────────────────┘
                            │ HTTPS
                            ▼
               ┌──────────────────────────┐
               │  {space}.backlog.com/api  │
               │    Backlog REST API v2    │
               └──────────────────────────┘

---

System Prompt Instructions

You are the Backlog Agent, a project management automation specialist for Nulab Backlog. Follow these rules precisely:

1. Authenticate using API key (apiKey query parameter) by default. Support OAuth2 for user-context operations. Never embed API keys in log output.
2. All API requests target https://{BACKLOG_SPACE_ID}.backlog.com/api/v2/ or https://{BACKLOG_SPACE_ID}.backlog.jp/api/v2/. Auto-detect the correct domain based on space configuration.
3. Issue keys follow the {PROJECT_KEY}-{NUMBER} convention (e.g., DEV-42). Always resolve project keys and issue numbers to internal numeric IDs before making API calls. Display keys in human-readable format in output.
4. Support all issue fields: issueType, priority (High/Medium/Low), status (Open/In Progress/Resolved/Closed), assignee, category, version, milestone, startDate, dueDate, estimatedHours, actualHours, resolution, and custom fields.
5. When creating issues, validate that the specified issue type, priority, and assignee exist in the target project. Provide helpful suggestions on mismatch.
6. Wiki pages use Backlog's native markup format by default. Support Markdown when the project has Markdown enabled. Auto-detect the project's wiki format setting.
7. Git operations proxy through the Backlog API, not direct Git protocol. Support branch listing, pull request creation and review, and webhook management.
8. Pull requests require: summary, description, base branch, branch (source), and optionally assigneeId and issueId (to link to an issue).
9. Milestone operations must respect the project's milestone list. Auto-suggest existing milestones when creating issues. Milestones have startDate, releaseDueDate, and optional description.
10. Sprint board operations map to Backlog's "Board" feature. Issues move between statuses on the board. Track velocity by summing estimated hours across sprint milestones.
11. File attachments upload to the space's shared storage first (/api/v2/space/attachment), returning an id that can then be linked to issues, wiki pages, or pull requests.
12. Bulk operations use individual API calls (Backlog has no native bulk endpoint). The agent batches these with concurrency control and progress reporting. Maximum recommended: 100 operations per batch.
13. Notification preferences: respect the user's notification settings. Do not trigger excessive notifications during bulk operations -- use the notifiedUserId parameter selectively.
14. Custom fields are project-scoped. Fetch the project's custom field definitions before validating create/update payloads. Support types: Text, TextArea, Numeric, Date, SingleList, MultipleList, CheckBox, RadioButton.
15. Cross-project queries use the /api/v2/issues endpoint with projectId array. Always scope queries to specific projects unless the user explicitly requests space-wide search.
16. Gantt chart data is derived from issue start dates and due dates. When generating reports, validate that issues have both dates set. Warn about issues missing scheduling data.
17. Rate limiting: Backlog allows varying limits based on plan (Free: 60/min, Standard: 300/min, Premium: 600/min). Detect the plan from the space info endpoint and configure accordingly.
18. Handle Backlog's webhook events for CI/CD integration. Support event types: issue creation/update, wiki update, Git push, pull request, and file upload.
19. Always display timestamps in the project's configured timezone. Default to JST (Asia/Tokyo) for Japanese spaces.

---

Environment Variables

Variable	Required	Default	Description
BACKLOG_SPACE_ID	Yes	-	Your Backlog space identifier (e.g., myteam for myteam.backlog.com)
BACKLOG_API_KEY	Yes	-	API key from Personal Settings > API in Backlog
BACKLOG_PROJECT_KEY	No	-	Default project key (e.g., DEV) used when --project is omitted
BACKLOG_DOMAIN	No	backlog.com	Domain suffix: backlog.com (international) or backlog.jp (Japan)
BACKLOG_OUTPUT_FORMAT	No	table	Default output format: table, json, csv
BACKLOG_CONCURRENCY	No	3	Maximum concurrent API calls for bulk operations
BACKLOG_TIMEZONE	No	Asia/Tokyo	Timezone for displaying timestamps

---

Commands

bl issues

List issues with filtering.

$ bl issues --project DEV --status "In Progress" --assignee me

  Key       Type     Priority  Summary                          Assignee     Due Date     Updated
  ────────  ───────  ────────  ───────────────────────────────  ───────────  ───────────  ──────────
  DEV-142   Task     High      API認証モジュールのリファクタ     石原 達也     2026-03-07   2h ago
  DEV-138   Bug      High      ログイン時のCSRFトークンエラー    石原 達也     2026-03-05   5h ago
  DEV-135   Task     Medium    CI/CDパイプライン最適化           石原 達也     2026-03-10   1d ago
  DEV-131   Feature  Medium    ダッシュボード通知機能追加        石原 達也     2026-03-15   2d ago
  DEV-127   Task     Low       ドキュメント英語化対応            石原 達也     2026-03-20   3d ago

  Showing 5 issues (In Progress, assigned to 石原 達也) in project DEV

bl create

Create a new issue.

$ bl create --project DEV --type Bug --priority High \
    --summary "本番環境でのメモリリーク検出" \
    --description "Production server memory usage increasing 2%/hour since deploy v2.3.1. GC logs show unreleased connections in ConnectionPool." \
    --assignee ishihara --milestone "v2.3.2" --due "2026-03-05"

  Issue created successfully
  Key:         DEV-143
  Type:        Bug
  Priority:    High
  Summary:     本番環境でのメモリリーク検出
  Assignee:    石原 達也
  Milestone:   v2.3.2
  Due Date:    2026-03-05
  Status:      Open
  Created:     2026-03-01 11:42:18 JST
  URL:         https://myteam.backlog.com/view/DEV-143

bl update

Update an existing issue.

$ bl update DEV-143 --status "In Progress" --actual-hours 2.5 \
    --comment "Root cause identified: connection pool not closing idle connections. Fix in PR #89."

  Issue updated successfully
  Key:         DEV-143
  Changes:
    Status:        Open → In Progress
    Actual Hours:  0 → 2.5h
  Comment:     Added (ID: 45678)
  Updated:     2026-03-01 14:15:33 JST
  URL:         https://myteam.backlog.com/view/DEV-143

bl wiki

Create and manage wiki pages.

$ bl wiki --project DEV --list

  Page ID   Title                              Updated By     Updated        Tags
  ────────  ─────────────────────────────────  ─────────────  ─────────────  ──────────────
  W-001     プロジェクト概要                    石原 達也      2026-02-28     overview
  W-002     開発環境セットアップ手順            佐藤 花子      2026-02-25     setup, dev
  W-003     API設計ガイドライン                 田中 太郎      2026-02-20     api, design
  W-004     デプロイ手順書                      石原 達也      2026-03-01     deploy, ops
  W-005     障害対応フロー                      山田 次郎      2026-02-15     incident

  Total: 5 wiki pages in project DEV

bl milestone

Manage project milestones and versions.

$ bl milestone --project DEV

  Name       Start Date   Release Due   Issues   Progress   Status
  ─────────  ───────────  ────────────  ───────  ─────────  ────────
  v2.3.0     2026-01-15   2026-02-15    28/28    100%       Released
  v2.3.1     2026-02-01   2026-02-28    24/24    100%       Released
  v2.3.2     2026-03-01   2026-03-15    8/18     44%        Active
  v2.4.0     2026-03-15   2026-04-30    0/32     0%         Planned

  Active: v2.3.2 (10 open issues, 8 closed, target: 2026-03-15)

bl sprint

View and manage sprint boards.

$ bl sprint --project DEV --current

  Sprint: v2.3.2 Sprint 1 (2026-03-01 → 2026-03-15)

  ┌─────────────────┬─────────────────┬─────────────────┬─────────────────┐
  │  Open (3)       │  In Progress(5) │  Resolved (6)   │  Closed (4)     │
  ├─────────────────┼─────────────────┼─────────────────┼─────────────────┤
  │  DEV-140 [M]    │  DEV-142 [H]    │  DEV-130 [H]    │  DEV-125 [M]    │
  │  デプロイ自動化  │  API認証リファ   │  DB最適化        │  UIテスト追加    │
  │                 │                 │                 │                 │
  │  DEV-139 [L]    │  DEV-138 [H]    │  DEV-129 [M]    │  DEV-124 [L]    │
  │  コード整理      │  CSRFバグ修正   │  キャッシュ導入   │  README更新     │
  │                 │                 │                 │                 │
  │  DEV-137 [M]    │  DEV-135 [M]    │  DEV-128 [M]    │  DEV-123 [M]    │
  │  E2Eテスト      │  CI/CD最適化     │  ログ集約        │  依存関係更新    │
  │                 │                 │                 │                 │
  │                 │  DEV-131 [M]    │  DEV-126 [H]    │  DEV-122 [H]    │
  │                 │  通知機能追加    │  セキュリティ    │  認証バグ修正    │
  │                 │                 │                 │                 │
  │                 │  DEV-127 [L]    │  DEV-133 [L]    │                 │
  │                 │  ドキュメント    │  型定義整理      │                 │
  │                 │                 │                 │                 │
  │                 │                 │  DEV-134 [M]    │                 │
  │                 │                 │  APIテスト       │                 │
  └─────────────────┴─────────────────┴─────────────────┴─────────────────┘

  Velocity: 42h estimated | 28h completed | Burndown: 56% at day 1/14

bl git

Manage Git repositories and pull requests.

$ bl git --project DEV --repos

  Repository     Default Branch  Last Push        Commits  PRs Open
  ─────────────  ──────────────  ───────────────  ───────  ────────
  dev-api        main            2026-03-01 10:22  1,842    3
  dev-frontend   main            2026-03-01 09:45  2,156    2
  dev-infra      main            2026-02-28 18:30  487      0

  Total: 3 repositories | 5 open pull requests

$ bl git --project DEV --repo dev-api --prs

  PR #    Title                              Author       Base    Branch          Status
  ─────  ───────────────────────────────────  ───────────  ──────  ──────────────  ────────
  #89    Fix connection pool memory leak      石原 達也     main    fix/mem-leak    Open
  #88    Add rate limiting middleware          佐藤 花子     main    feat/rate-limit Review
  #87    Update dependency versions            田中 太郎     main    chore/deps      Merged

bl search

Search across issues, wiki, and comments.

$ bl search "memory leak" --project DEV --scope issues,wiki

  Issues (3 matches):
  DEV-143  [Bug/High]     本番環境でのメモリリーク検出        In Progress
  DEV-098  [Bug/Medium]   ステージングメモリリーク調査         Closed
  DEV-055  [Task/Low]     メモリプロファイリングツール導入     Closed

  Wiki (1 match):
  W-005  障害対応フロー  Section: "メモリリーク発生時の対応手順"

  Total: 4 results across issues and wiki

bl report

Generate project status reports.

$ bl report --project DEV --type weekly

  Weekly Report: DEV (2026-02-24 → 2026-03-01)

  Summary:
    Issues Created:    12
    Issues Closed:     8
    Issues In Review:  4
    Avg Resolution:    3.2 days

  By Priority:
    High:    3 created / 2 closed
    Medium:  7 created / 5 closed
    Low:     2 created / 1 closed

  By Assignee:
    石原 達也     4 closed (16.5h actual)
    佐藤 花子     2 closed (8.0h actual)
    田中 太郎     1 closed (4.5h actual)
    山田 次郎     1 closed (3.0h actual)

  Milestone Progress:
    v2.3.2: 44% (8/18 issues closed, 7 days remaining)

  Blockers:
    DEV-143 [High] Memory leak in production — needs immediate attention

bl bulk

Perform bulk operations on issues.

$ bl bulk --project DEV --action update --query "milestone:v2.3.1 AND status:Resolved" \
    --set '{"status": "Closed", "resolution": "Fixed"}'

  Bulk update preview:
  Project:    DEV
  Matching:   12 issues
  Action:     Set status → Closed, resolution → Fixed

  Proceed? [y/N]: y

  Processing: [████████████████████████████████████████] 12/12

  Bulk update complete
  Updated:    12 issues
  Failed:     0
  Duration:   4.8 seconds

  Affected:   DEV-112, DEV-113, DEV-114, DEV-115, DEV-116, DEV-117,
              DEV-118, DEV-119, DEV-120, DEV-121, DEV-122, DEV-124

---

Workflow

  Developer                  Backlog Agent                 Backlog API
  ─────────                  ─────────────                 ───────────
      │                            │                            │
      │  bl create --project DEV   │                            │
      │  --type Bug --priority H   │                            │
      ├───────────────────────────►│                            │
      │                            │  Resolve project key → ID  │
      │                            │  Validate issue type       │
      │                            │  Validate assignee         │
      │                            │  Resolve milestone name    │
      │                            │                            │
      │                            │  POST /api/v2/issues       │
      │                            ├───────────────────────────►│
      │                            │  201 {id, issueKey, ...}   │
      │                            │◄───────────────────────────┤
      │  DEV-143 created           │  Map IDs → readable keys   │
      │◄───────────────────────────┤                            │
      │                            │                            │
      │  bl update DEV-143         │                            │
      │  --status "In Progress"    │                            │
      ├───────────────────────────►│                            │
      │                            │  Resolve DEV-143 → ID      │
      │                            │  Map status → statusId     │
      │                            │  PATCH /api/v2/issues/{id} │
      │                            ├───────────────────────────►│
      │                            │  200 OK                    │
      │                            │◄───────────────────────────┤
      │  DEV-143 updated           │                            │
      │◄───────────────────────────┤                            │
      │                            │                            │
      │  bl sprint --current       │                            │
      ├───────────────────────────►│  GET milestones, issues    │
      │                            ├───────────────────────────►│
      │                            │◄───────────────────────────┤
      │  Sprint board rendered     │  Group by status           │
      │◄───────────────────────────┤  Calculate velocity        │
      │                            │                            │

---

Error Handling

Error	Cause	Solution
401 Unauthorized: Authentication failed	API key is invalid, expired, or not set	Regenerate your API key at Personal Settings > API in Backlog. Verify BACKLOG_API_KEY is correctly set.
404 Not Found: Project not found	Project key is invalid or you do not have access	Verify the project key with bl issues --list-projects. Ensure your account has been added to the project.
400 Invalid issue type	The specified issue type does not exist in this project	Each project defines its own issue types. Use bl issues --project KEY --types to list valid types for the project.
400 Duplicate issue key	Attempting to create an issue with a key that already exists	Issue keys are auto-generated. This error typically indicates a race condition. Retry the creation.
403 Forbidden: Insufficient privileges	Your role does not permit this operation (e.g., guest trying to delete)	Contact the project admin to upgrade your role. Guests have read-only access by default.
413 File too large	Attachment exceeds the space's file size limit (varies by plan)	Free plan: 100MB total storage. Compress files or use external storage with links. Check bl status for storage usage.
429 Rate Limit Exceeded	Too many requests for your plan tier	Agent automatically backs off. Free: 60/min, Standard: 300/min, Premium: 600/min. Use --concurrency 1 for conservative mode.

---

FAQ

1. How do I get a Backlog API key? Log in to Backlog, go to Personal Settings > API > Register new API key. Copy the key and set it as BACKLOG_API_KEY.

2. What is the difference between backlog.com and backlog.jp? backlog.jp is the legacy Japanese domain. backlog.com is the current international domain. Both work identically. Set BACKLOG_DOMAIN to match your space's domain.

3. Can I create issues across multiple projects in one command? Yes, use bl create --project DEV,QA,OPS --type Task --summary "Quarterly review" to create the same issue template across projects.

4. How do I link issues to Git pull requests? Include the issue key in the PR description or use bl git --pr-create --issue DEV-143. Backlog automatically links PRs that reference issue keys in commit messages.

5. Can I export Gantt chart data? Yes. bl report --project DEV --type gantt --format csv exports all issues with start/due dates suitable for external Gantt tools. Include --include-subtasks for work breakdown structures.

6. How do sprint boards work in Backlog? Sprints map to milestones with date ranges. bl sprint --current shows issues grouped by status for the active milestone. Velocity is calculated from estimated vs actual hours.

7. Can I manage multiple spaces from one CLI? Yes. Use --space other-team to override BACKLOG_SPACE_ID per command, or maintain multiple config profiles in ~/.backlog-agent/config.yaml.

8. How do I bulk-import issues from CSV? Use bl bulk --import ./issues.csv --project DEV. The CSV must include columns matching field names (Summary, Type, Priority, Assignee, etc.). The agent validates all rows before importing.

9. Does the agent support Backlog's webhook events? Yes. bl webhook --create --project DEV --url https://ci.jenkins-server.local/webhook/backlog --events issue_created,git_pushed configures event notifications for CI/CD integration.

10. Can I track time spent on issues? Yes. Use bl update DEV-143 --actual-hours 4.5 to log time. bl report --project DEV --type timesheet --period 2026-03 generates timesheet reports grouped by assignee.

11. How do I manage wiki page attachments? Upload: bl wiki --project DEV --page W-001 --attach ./diagram.png. The file is uploaded to shared storage and linked to the wiki page.

12. What markup formats does the wiki support? Backlog supports its own markup and Markdown (project setting). The agent auto-detects the format. Use --format markdown or --format backlog to force a specific format.

---

Data Storage

The Backlog Agent maintains local state for efficient operations:

~/.backlog-agent/
├── config.yaml                # Space, API key, default project settings
├── cache/
│   ├── spaces/
│   │   └── myteam.json        # Space info cache (TTL: 1 hour)
│   ├── projects/
│   │   ├── DEV.json           # Project metadata cache (TTL: 15 min)
│   │   ├── DEV_types.json     # Issue types cache (TTL: 1 hour)
│   │   ├── DEV_statuses.json  # Status list cache (TTL: 1 hour)
│   │   └── DEV_members.json   # Member list cache (TTL: 15 min)
│   └── recent_issues.json     # Recently accessed issues (TTL: 5 min)
├── templates/
│   ├── bug_report.json        # Issue creation templates
│   ├── feature_request.json
│   └── weekly_report.md       # Report generation templates
├── logs/
│   ├── api-2026-03.log        # Monthly API log (keys redacted)
│   ├── bulk_operations.log    # Bulk operation audit trail
│   └── errors.log             # Error details with context
└── exports/
    └── DEV_report_20260301.csv  # Generated reports (auto-cleanup: 30 days)

Project metadata and type definitions are cached aggressively since they change infrequently, dramatically reducing API calls during interactive sessions. Issue caches use short TTLs to ensure data freshness. All API keys are redacted from logs.

---

Comparison

Feature	Backlog Agent	Jira CLI	GitHub CLI	Linear CLI	Redmine CLI
Japanese UI/docs	Native (JP + EN)	Plugin required	EN only	EN only	Plugin
Issue tracking	Full CRUD + custom fields	Full CRUD	Issues only	Full CRUD	Full CRUD
Wiki built-in	Yes (native)	Confluence (separate)	No (use repo)	No	Yes
Git hosting	Built-in	Bitbucket (separate)	Native	No	Plugin
Gantt charts	Native	Plugin/Cloud	No	Cycles	Plugin
Sprint boards	Milestone-based	Scrum/Kanban	Projects	Cycles	Plugin
File storage	Per-space quota	Unlimited (Cloud)	LFS	No	Per-project
Pull requests	Built-in	Bitbucket	Native	No	No
Cross-project search	Yes	JQL	Limited	Yes	Yes
Pricing (small team)	Free (10 users)	Free (10 users)	Free (unlimited)	Free (250 issues)	Free (OSS)
Target market	Japan / APAC	Global	Global (developers)	Startups	Self-hosted