# create-cli

> CLI パラメータと UX 設計：引数、フラグ、サブコマンド、ヘルプテキスト、出力形式、エラーメッセージ、終了コード、プロンプト、設定/環境変数の優先順位、安全/dry-run 動作。CLI 仕様設計（実装前）や既存 CLI のリファクタに使用。

- Author: Yasuhito Takamiya
- Repository: yasuhito/agent-kit
- Version: 20260202093404
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/yasuhito/agent-kit
- Web: https://mule.run/skillshub/@@yasuhito/agent-kit~create-cli:20260202093404

---

---
name: create-cli
description: CLI パラメータと UX 設計：引数、フラグ、サブコマンド、ヘルプテキスト、出力形式、エラーメッセージ、終了コード、プロンプト、設定/環境変数の優先順位、安全/dry-run 動作。CLI 仕様設計（実装前）や既存 CLI のリファクタに使用。
---

# Create CLI

CLI 設計（構文 + 動作）、人間優先、スクリプトフレンドリー。

## 最初にやること

- `agent-kit/skills/create-cli/references/cli-guidelines.md` を読んでデフォルト基準として適用
- 上流/完全ガイドライン: https://clig.dev/
- インターフェースを決めるのに必要な最小限の確認質問のみ

## 確認（高速）

質問し、ユーザーが不明な場合はベストゲスのデフォルトで進む:

- コマンド名 + 一文の目的
- 主なユーザー: 人間、スクリプト、または両方
- 入力ソース: 引数 vs stdin、ファイル vs URL、シークレット（フラグ経由は禁止）
- 出力契約: 人間用テキスト、`--json`、`--plain`、終了コード
- 対話性: プロンプト許可？`--no-input` 必要？破壊的操作の確認？
- 設定モデル: フラグ/環境変数/設定ファイル、優先順位、XDG vs リポジトリローカル
- プラットフォーム/ランタイム制約: macOS/Linux/Windows、単一バイナリ vs ランタイム

## 成果物（出力するもの）

CLI 設計時、ユーザーが実装できるコンパクトな仕様を作成:

- コマンドツリー + USAGE 概要
- 引数/フラグ表（型、デフォルト、必須/任意、例）
- サブコマンドの意味（各動作、冪等性、状態変更）
- 出力ルール: stdout vs stderr、TTY 検出、`--json`/`--plain`、`--quiet`/`--verbose`
- エラー + 終了コードマップ（主な失敗モード）
- 安全ルール: `--dry-run`、確認、`--force`、`--no-input`
- 設定/環境変数ルール + 優先順位（フラグ > 環境変数 > プロジェクト設定 > ユーザー設定 > システム）
- シェル補完（該当する場合）
- 5-10 の実行例（一般的なフロー、パイプ/stdin 例を含む）

## デフォルト規約

- `-h/--help` は常にヘルプを表示し他の引数を無視
- `--version` はバージョンを stdout に出力
- 主要データは stdout、診断/エラーは stderr
- 機械出力用に `--json` を追加、安定した行ベーステキスト用に `--plain` を検討
- プロンプトは stdin が TTY の時のみ、`--no-input` でプロンプト無効化
- 破壊的操作: 対話的確認 + 非対話的は `--force` または明示的 `--confirm=...` が必要
- `NO_COLOR`、`TERM=dumb` を尊重、`--no-color` を提供
- Ctrl-C: 高速終了、制限付きクリーンアップ、可能なら crash-only

## テンプレート

### CLI 仕様スケルトン

```
1. **名前**: `mycmd`
2. **一文説明**: `...`
3. **USAGE**:
   - `mycmd [global flags] <subcommand> [args]`
4. **サブコマンド**:
   - `mycmd init ...`
   - `mycmd run ...`
5. **グローバルフラグ**:
   - `-h, --help`
   - `--version`
   - `-q, --quiet` / `-v, --verbose`
   - `--json` / `--plain`
6. **I/O 契約**:
   - stdout:
   - stderr:
7. **終了コード**:
   - `0` 成功
   - `1` 一般的な失敗
   - `2` 無効な使用法（パース/検証）
8. **環境変数/設定**:
   - 環境変数:
   - 設定ファイルパス + 優先順位:
9. **例**:
   - …
```