CLIツール

specdown CLIは、SpecDownをターミナルからGitライクに扱うためのツールです。 単一ファイル操作、ローカルフォルダ同期、画像アップロードに対応しています。

インストール

npm（推奨）

npm install -g specdown-cli

npx（インストール不要）

npx specdown-cli --help

認証

ログイン

specdown login

メールとパスワードの入力を求められます。セッショントークンは~/.specdown/config.jsonに保存されます。

ログアウト

specdown logout

現在のユーザー確認

specdown whoami
# → user@example.com
# → ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# → Project: my-api-docs (my-api-docs)

プロジェクト管理

プロジェクト一覧

specdown projects
# * my-api-docs   (active)
#   team-handbook
#   mobile-spec

アクティブプロジェクトの切り替え

specdown use my-api-docs

アクティブプロジェクトは単一ファイル操作と画像アップロードの既定値として使われます。

ローカルフォルダをプロジェクトにリンク

# 現在のフォルダをリンク
specdown link my-api-docs

# 別フォルダをリンク
specdown link my-api-docs --dir ./docs

# リモートの一部パスだけを対象にする
specdown link my-api-docs --prefix /guides

リンクすると選択したフォルダに.specdown/project.jsonが作成され、 project・remote prefix・sync設定が保存されます。

リンク解除

specdown unlink
specdown unlink --dir ./docs

リンク済みフォルダ同期

リンク後、そのローカルフォルダはSpecDownプロジェクトのworking copyとして扱われます。 CLIは.specdown/sync-state.jsonに前回同期状態を保存し、ローカル変更・リモート変更・ conflictを判定します。

同期状態を確認

specdown status
specdown status --dir ./docs

変更予定を確認

specdown diff
specdown diff --dir ./docs

diffは、push・pull・作成・削除・conflictになるファイルを事前に表示します。

双方向syncを実行

# 非conflict変更を双方向で反映
specdown sync

# linked folderのcontinuous sync
specdown sync --watch --yes

# conflictがあっても非conflict分だけ進める
specdown sync --force --yes

syncはpushとpullの双方向版です。localとremoteの 非conflict変更を1回で反映します。watch modeではfile eventをdebounceし、2つのsyncが同時に走りません。

リンク済みフォルダをpush

# 確認後にpush
specdown push

# CIや自動化向け
specdown push --yes

# conflictがあってもリモートを上書き
specdown push --force

# 別のリンク済みフォルダを指定
specdown push --dir ./docs

リンク済みフォルダをpull

# SpecDownからローカルへ取り込む
specdown pull

# 確認プロンプトをスキップ
specdown pull --yes

# ローカルconflictをリモートで上書き
specdown pull --force

単一ドキュメント操作

ドキュメント一覧

specdown ls
# my-api-docs
# ├── 📁 guides
# │   ├── 📄 authentication   guides/authentication
# │   └── 📄 endpoints        guides/endpoints
# └── 📄 changelog            changelog

ドキュメントを読む

# 全文
specdown read guides/authentication

# 10-25行のみ
specdown read guides/authentication --from 10 --to 25

# 行番号付き
specdown read guides/authentication -n

# 他のツールへパイプ
specdown read changelog | grep "v2"

readはraw Markdownをそのまま出力します。AIプロンプトやshell pipelineには 必要な行範囲だけ渡すのが便利です。

ローカルファイルをpush

# ローカルファイルをドキュメントパスにアップロード
specdown push ./README.md changelog

# ドキュメントがない場合は自動作成
specdown push ./auth-spec.md guides/authentication

ドキュメントをpull

# ファイルにダウンロード
specdown pull guides/authentication ./auth.md

# stdoutに出力
specdown pull changelog

新規ドキュメントまたはフォルダ作成

# 新規ドキュメント
specdown new "OAuth Flow"

# フォルダ内にドキュメント作成
specdown new "OAuth Flow" --parent guides

# 新規フォルダ
specdown new "API Reference" --folder

ドキュメント削除

# 確認プロンプト付き
specdown rm guides/old-api

# 確認をスキップ
specdown rm guides/old-api --force

画像アップロード

# 画像をアップロードし、Markdownリンクを表示
specdown image ./architecture.png

# 特定ドキュメントに紐付けてアップロード
specdown image ./diagram.png --doc /guides/authentication.md

画像はSpecDownに保存され、ドキュメントへ貼り付けられるMarkdownリンクが出力されます。

プロジェクト添付ファイル

# project fileをアップロード。HTML/HTMは編集可能、その他はembed referenceを表示
specdown file upload ./assets/login-flow.png /assets/login-flow.png
specdown file upload ./pages/landing.html /pages/landing.html

# project attachmentsを一覧表示
specdown file list
specdown file list /assets

# text-like fileを読む、またはbinary fileのmetadata/download infoを表示
specdown file read /assets/config.json
specdown file read /assets/login-flow.png ./login-flow.png

PDF、画像、動画、CSV、text-like fileをfile treeに追加するにはfile uploadを使います。HTML/HTMは編集可能なドキュメントになり、その他のfileは preview-only attachmentとして追加され、Markdownから[@/path/to/file]で埋め込めます。

コメント

ドキュメントのコメントスレッド（共有ビューでアンカーされたコメントを含む）を読み取ります。 匿名コメントは Anonymous として表示され、ログインユーザーのコメントは名前で表示されます。

# ドキュメントのスレッドとリプライをすべて表示
specdown comments list guides/authentication

# 解決済みスレッドを除外
specdown comments list guides/authentication --unresolved

# スクリプト / AI 連携用に JSON で出力
specdown comments list guides/authentication --json

出力ではリプライが親スレッドの下にまとめられ、各スレッドの上に コメントがアンカーされている選択テキスト（引用）が表示されます。

AI Skills

SpecDown には AI アシスタント向けのスキル束（Anthropic SKILL.md 形式）が同梱されています。 Claude Code・Cursor・Codex・OpenCode・Antigravity、あるいは汎用の .agents/ ツール まで、自前でプロンプトを書かずに SpecDown 専用のコンテキストとワークフローを取り込めます。

# カレントディレクトリで検出した AI ツール用にインストール（対話）
specdown install skills

# 非対話: ターゲットを明示
specdown install skills --for claude
specdown install skills --for cursor
specdown install skills --for codex

# バンドル済みとキャッシュの状態を確認
specdown skills status

実行のたびに、インストール済み CLI に同梱されたスキルから ~/.specdown/skills/ をリフレッシュし、各 AI ツールの想定ディレクトリ （.claude/skills/、Cursor 用の .mdc にフラット化した .cursor/rules/、.codex/skills/ など）へコピーします。npm i -g specdown-cli@latest 後にもう一度実行すれば最新スキルを取り込めます。

検索

# プロジェクト内全ドキュメントを検索
specdown search "rate limiting"

# 特定ファイルのみ検索
specdown search "TODO" --files "guides/api,changelog"

# マッチ周辺のコンテキスト行を追加
specdown search "authentication" -C 5

マッチはターミナルで強調表示され、周辺のコンテキスト行付きで表示されます。

コマンドリファレンス

CI/CDでの使用

対話プロンプトを避けるため、認証情報を環境変数で設定します:

# GitHub Actions例
- name: Sync docs to SpecDown
  env:
    SPECDOWN_EMAIL: ${{ secrets.SPECDOWN_EMAIL }}
    SPECDOWN_PASSWORD: ${{ secrets.SPECDOWN_PASSWORD }}
  run: |
    npx specdown-cli login
    npx specdown-cli use my-api-docs
    npx specdown-cli link my-api-docs --dir ./docs
    npx specdown-cli sync --dir ./docs --yes

ユースケースとヒント

AIがMarkdown仕様を操作する

CLIはAIフレンドリーです。エージェントはシェルから直接呼び出し、 ローカルworking copyを保ちつつ、仕様を読み、画像を追加し、SpecDownへ同期できます。

# AIエージェントの例
specdown link my-api-docs --dir ./specs
specdown status --dir ./specs
specdown read api/authentication
specdown image ./screenshots/login.png --doc /api/authentication.md
specdown sync --dir ./specs --yes

force前に同期内容を確認する

specdown status --dir ./docs
specdown diff --dir ./docs

# 計画を確認してから実行
specdown sync --dir ./docs --yes
# または
specdown pull --dir ./docs --force --yes

ターミナルからスクリーンショットや図を追加

specdown image ./artifacts/sequence-diagram.png --doc /guides/authentication.md
# -> ![sequence-diagram.png](/r/your-project/...png)

返ってきたMarkdownリンクは、そのままドキュメントやPRコメントに貼り付けられます。

ローカルで編集してSpecDownへ公開

# ローカルエディターで編集
code ./docs

# 同期内容を確認
specdown diff --dir ./docs

# localとremoteを揃える
specdown sync --dir ./docs

作業中のlocal mirrorを常時同期する

# linked folderごとにwatch loopを起動
specdown sync --dir ./docs --watch --yes

AIエージェントやローカルエディターがMarkdownを編集しつつ、チームメンバーがweb appでも編集する状況に向いています。 非conflict変更は自動同期され、conflictはレビュー用に残ります。

単一ドキュメントを他ツールへ渡す

# ドキュメントをローカルファイルへ保存
specdown pull /api/overview.md ./README.md

# 必要な範囲だけ別コマンドへ渡す
specdown read /api/overview.md --from 20 --to 60 | sed -n '1,12p'

ヒントとトリック

• 長期作業はリンク済みフォルダで: link、status、diff、その後にpushまたはpull。
• 日常のmirrorにはsync: local/remoteの非conflict変更を1回で反映できます。
• 小さな自動化は単一ファイルモードで: push <file> <doc-path> と pull <doc-path> [out-file] を維持。
• 上書き前に確認: まずdiffを実行。--forceは片方向で勝たせたい場合だけ。
• watch modeは自動化向け: 確認プロンプトで止まらないよう specdown sync --watch --yes を使います。
• 行範囲を使う: --from / --to はAIプロンプトを短く保つのに便利です。
• 画像は適切なdocに紐付ける: 特定ドキュメントに関連付けたい場合はspecdown image --doc /pathを使います。