npm package: @niiiiiiile/iw-backlog-cli
Description: CLI for Nulab Backlog issue and project management
Author: Teruaki Iwane
Latest version: 0.1.0

# backlog-cli

`backlog-cli` は [Nulab Backlog](https://backlog.com/) の課題・プロジェクトをターミナルから操作する CLI ツールです。`setup` / `profile` による接続情報管理と、`issue` / `project` / `whoami` による日常操作を一貫したフローで提供します。

![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white)
![CLI](https://img.shields.io/badge/interface-CLI-4D4D4D)
![License](https://img.shields.io/badge/license-MIT-blue)

## Table of contents

* [Overview](#overview)
* [Features](#features)
* [Installation](#installation)
  + [Install globally](#install-globally)
  + [Run with npx](#run-with-npx)
  + [Run from source](#run-from-source)
* [Quick start](#quick-start)
* [Profiles](#profiles)
* [Environment variables](#environment-variables)
* [Authentication check](#authentication-check)
* [Credential precedence](#credential-precedence)
* [Usage](#usage)
  + [Issue commands](#issue-commands)
  + [Project commands](#project-commands)
  + [Profile commands](#profile-commands)
* [Development](#development)
* [License](#license)

## Overview

`backlog-cli` は Backlog の API をシンプルに扱うための CLI です。初回は `backlog setup` で接続情報を保存し、その後は `backlog issue ...` や `backlog project ...` をそのまま実行できます。複数スペースを扱う場合も `profile` で切り替えできます。

## Features

- 課題の一覧取得・詳細確認・作成・更新・削除・コメント操作
- プロジェクト一覧取得・詳細確認
- `setup` / `profile` による複数スペース管理
- `whoami` による接続確認
- フラグ / プロファイル / 環境変数の優先順位による資格情報解決

## Installation

### Install globally

```bash
npm install -g @niiiiiiile/iw-backlog-cli
```

### Run with npx

```bash
npx @niiiiiiile/iw-backlog-cli --help
npx @niiiiiiile/iw-backlog-cli issue list
```

### Run from source

```bash
git clone https://github.com/Niiiiile/backlog-cli.git
cd backlog-cli
npm install
npm run dev -- --help
```

## Quick start

```bash
backlog setup \
  --url https://yourspace.backlog.com \
  --api-key YOUR_API_KEY \
  --project-key MYPROJECT
```

初回登録時は `default` プロファイルに保存され、自動でデフォルトになります。

## Profiles

複数スペースを使い分ける場合は `profile` を使います。

```bash
# work プロファイルを追加
backlog profile add work \
  --url https://yourspace.backlog.com \
  --api-key YOUR_API_KEY \
  --project-key MYPROJECT

# プロファイル一覧
backlog profile list

# デフォルト切り替え
backlog profile use work

# 実行時だけ別プロファイルを使う
backlog issue list --profile work
```

## Environment variables

`.env.example` を参考に環境変数を設定することもできます。

```bash
export BACKLOG_BASE_URL=https://yourspace.backlog.com
export BACKLOG_API_KEY=your_api_key_here
export BACKLOG_PROJECT_KEY=MYPROJECT
```

## Authentication check

```bash
backlog whoami
```

## Credential precedence

1. コマンドフラグ（`--url`, `--api-key`, `--project-key`）
2. 設定ファイルのプロファイル（`--profile` または default）
3. 環境変数（`BACKLOG_BASE_URL`, `BACKLOG_API_KEY`, `BACKLOG_PROJECT_KEY`）

## Usage

```bash
backlog --help
```

### Issue commands

| サブコマンド | 説明 |
|---|---|
| `list` | 課題の一覧を取得（キーワード・ステータス・担当者でフィルタ可） |
| `get <issueIdOrKey>` | 課題の詳細を取得 |
| `add` | 課題を作成 |
| `update <issueIdOrKey>` | 課題を更新（ステータス変更・コメント追加など） |
| `delete <issueIdOrKey>` | 課題を削除 |
| `comments <issueIdOrKey>` | コメント一覧を取得 |
| `comment-add <issueIdOrKey> <content>` | コメントを追加 |

```bash
# 最新20件を取得
backlog issue list

# キーワード検索
backlog issue list --keyword バグ

# 未対応・処理中のみ
backlog issue list --status-id 1,2

# 課題の詳細
backlog issue get PROJ-123

# 課題を作成
backlog issue add --summary "画面表示のバグ" --issue-type-id 2 --priority-id 2

# ステータスを完了に変更しコメントを追加
backlog issue update PROJ-123 --status-id 4 --comment "対応完了"

# コメント一覧
backlog issue comments PROJ-123
```

### Project commands

| サブコマンド | 説明 |
|---|---|
| `list` | 参加しているプロジェクトの一覧を取得 |
| `get <projectIdOrKey>` | プロジェクトの詳細を取得 |

```bash
backlog project list
backlog project get MYPROJECT
```

### Profile commands

| サブコマンド | 説明 |
|---|---|
| `list` | 登録済みプロファイルの一覧を表示 |
| `add <name>` | プロファイルを追加・更新 |
| `remove <name>` | プロファイルを削除 |
| `use <name>` | デフォルトプロファイルを変更 |

```bash
backlog profile add personal --url https://myspace.backlog.jp --api-key KEY2 --project-key MYPROJ

# プロファイル一覧
backlog profile list
```

## Development

```bash
# 依存関係のインストール
npm install

# TypeScript のビルド
npm run build

# ビルドなしで直接実行
npm run dev -- --help
```

## ライセンス

MIT