CLI (コマンドライン)

`@crowi/cli` でターミナルから wiki を検索・読み取り・作成・編集する

@crowi/cli は、ターミナルから Crowi を操作するための エンドユーザー向けコマンドラインツール です。npm i -g @crowi/cli で配布され、crowi という名前で使えます。HTTP のみで wiki を叩き (DB には触れません)、OAuth で あなた自身として ページの検索 / 読み取り / 作成 / 編集を行います。

運用者向けの admin-cli とは別物です

@crowi/cli (crowi) はエンドユーザーが自分の権限で HTTP 経由に使うツールです。MongoDB に直結して運用作業を行う @crowi/admin-cli (crowi-admin) とは役割が異なります。

認証

crowi は public OAuth クライアント で PKCE を使います (クライアントシークレットはありません)。トークンは ~/.config/crowi/contexts.json ($XDG_CONFIG_HOME を尊重) に ファイルモード 0600 の JSON として保存されます。

ログインの宛先 URL は、接続先 Crowi の 公開オリジン (OAuth issuer。通常は web を配信しているホスト) を指定します。3 つのフローがあります。

# 1. ブラウザ認可コード + PKCE (ローカルループバックにリダイレクト)
#    既定。システムブラウザが開きます
crowi login https://wiki.example.com

# 2. デバイス認可グラント (headless / SSH 用。ブラウザ非検出時は自動選択)
crowi login --device https://wiki.example.com

# 3. 事前に発行した個人アクセストークンを直接保存 (OAuth 往復なし)
crowi login --token <pat> https://wiki.example.com

個人アクセストークンは 設定 → パスワード/APIトークン/アカウント連携 から、スコープと有効期限を指定して発行します (アカウントとセキュリティ)。

ログイン状態は crowi whoami で確認できます (サインイン中のユーザーと有効なスコープを表示)。crowi logout でトークンを失効・削除します。

スコープ

既定のスコープは pages:read pages:write です。これでページの読み取り / 書き込み / リネーム / 削除 / ウォッチ、および whoami をカバーします。コメント・添付・ブックマークを扱うコマンドは、ログイン時にそれぞれのスコープを追加します。どのコマンドに何が必要かは crowi CLI のコマンド表を参照してください。

--scope は 既定を上書き します。ページ系も使い続けるなら pages:read pages:write も含めて列挙するか、アンブレラ read write を要求してください (サーバ側が発行可能な全 *:read / *:write に展開します)。

crowi login https://wiki.example.com --scope "pages:read pages:write comments:read comments:write"
crowi login https://wiki.example.com --scope "read write"   # 発行可能な全権限

--scope はリクエスト送信前に サーバの発行可能カタログと照合 されるため、タイプミスや、そもそも発行できない管理者向けスコープは即座に弾かれます。管理者向けスコープを必要とする CLI コマンドはありません。

スコープが足りないコマンドを実行したとき

事前チェックは行わず、コマンドは実際に API を叩きます。スコープが不足していると、サーバが 403 INSUFFICIENT_SCOPE を返し、CLI はそれを 実行可能なヒント に変換して非ゼロ終了 (コード 3) します。

$ crowi comment add /onboarding -m "looks good"
crowi: your token lacks the required scope — re-login granting it: `crowi login --scope "comments:write"`

クラッシュも黙殺もせず、「どのスコープが要るか」と「どう再ログインするか」を提示して落ちます。

プロファイル (マルチエンドポイント / マルチアカウント)

複数の Crowi サーバ・アカウントを名前付きプロファイルで併用できます (gh / kubectl の context と同型)。トークンは エンドポイント単位 で保存されます。

-p, --profile <alias> はどのコマンドでも、コマンド名の 前後どちらにも 置けます。コマンド名より後ろに置く場合は、<url> のような引数の前後どちらでも構いません (login の position 引数とは独立な option なので)。両方に指定した場合はコマンド名以降 (コマンド側) の指定が優先されます:

# コマンド名の後、引数の後ろ (自然な語順)
crowi login https://wiki.almoha.net --profile almoha
crowi login https://strk-wiki.example.com --profile p2b

# コマンド名の後、引数の前でも同じ意味
crowi login --profile almoha https://wiki.almoha.net

# コマンド名の前 (従来の global option としての書き方)
crowi --profile almoha search "release notes"

crowi profiles            # 設定済みプロファイル一覧 (ローカル。通信なし)

# 両方に指定した場合は new が使われる (コマンド側が優先)
crowi --profile old login https://wiki.example.com --profile new

有効なプロファイルは --url / --token → --profile / $CROWI_PROFILE → 保存された current プロファイルの順で解決されます。

current プロファイルの切り替え

--profile を毎回指定したくない場合は、crowi profiles use <alias> で current プロファイル (--profile 未指定時の既定) を切り替えられます:

crowi profiles use almoha
crowi search "release notes"   # --profile なしで almoha に対して実行される

存在しない alias を指定すると、設定ファイルを変更せずに crowi: no such profile: <alias> を stderr へ出力し、終了コード 4 で終了します。crowi profiles の一覧表示では、切り替え方法のヒントが stderr に表示されます (--quiet で抑止可能。--json の出力形には影響しません)。

コマンド一覧

サブコマンド・固有のフラグ・必要なスコープの一覧は crowi CLI にあります。引数は送信前に対応する API リクエストスキーマで検証されるため、不正な path などは往復せずローカルで明確なエラーになります。

`edit` の競合 (409)

edit / update はページの revision_id を送って楽観ロックします。編集中にページが他で更新されると、書き込みは 既定で中断 され、終了コード 5 (conflict) を返します。黙って上書きはしません。新しいリビジョンを上書きしたい場合は --force を付けて再実行してください。

添付ファイルのダウンロード

attach list <path-or-id> は各行の先頭に添付 ID を出します。その ID を attach download に渡すとバイト列が取り出せます。

crowi attach list /docs/spec
# 6650f0c1a2b3c4d5e6f70123  design.pdf  /api/attachments/6650f0c1a2b3c4d5e6f70123

crowi attach download 6650f0c1a2b3c4d5e6f70123 -o design.pdf
crowi attach download 6650f0c1a2b3c4d5e6f70123 > design.pdf   # -o 省略時は stdout

-o を省略すると stdout に書き出します (端末に直接出力しようとした場合はバイナリで表示が壊れるため拒否します)。進捗や確認メッセージは stderr に出るので、リダイレクトやパイプにバイナリ以外が混ざることはありません。

ページに埋め込まれた画像の配信経路 (<img> が読む URL) は、添付が見つからないときにプレースホルダ画像を 200 で返します。ブラウザでは壊れた画像を出さずに済みますが、ファイルを取り出す用途では「中身のない画像を正常にダウンロードした」ことになってしまいます。attach download は専用の経路を使い、レコードが無い場合もストレージ上の実体が無い場合も 404 (終了コード 4) を返します。保存されたファイルは常に本物です。

添付ファイルのアップロード

attach add <path-or-id> <file> は、送信する前に サーバへ「何を受け付けるか」を聞きます (GET /api/attachments/upload-policy)。サーバが答えるのは、受理する MIME タイプの一覧・拡張子から MIME への対応表・経路ごとのサイズ上限です。CLI はこれを 2 つに使います。ファイル名の拡張子から宣言する Content-Type を決めることと、通らないと分かっているアップロードを送信前に手元で弾くことです。大きなファイルを送りきってから 413 を受け取る、という往復が無くなります。

手元で弾かれたときは終了コード 6 (invalid) で、理由が stderr に出ます:

upload rejected: video.mkv has type application/octet-stream, which this server does not accept for attachments

取得した policy はプロファイルに 10 分キャッシュされるので、実行のたびに往復はしません。この endpoint を持たない古いサーバは 404 を返し、CLI は同梱の拡張子テーブルに切り替えます — 事前チェックが無くなるだけで、アップロード自体は従来どおり動きます。

出力フォーマットとスクリプティング

search と ls は --format / --template で出力を整形でき、パイプ処理に向きます。指定できる値と終了コードの一覧は crowi CLI にあります。

# タブ区切りの path + score を 1 ヒット 1 行で
crowi search "release notes" --template '{{path}}\t{{score}}'

# 検索結果をそのまま取得へパイプ (get は - で stdin から path を読む)
crowi search onboarding --template '{{path}}' | head -1 | crowi get - > onboarding.md

進捗・警告はすべて stderr に出るため、--json の標準出力はスクリプト用にクリーンなままです。

シェル補完

# bash
eval "$(crowi completion bash)"
# zsh
crowi completion zsh > "${fpath[1]}/_crowi"
# fish
crowi completion fish > ~/.config/fish/completions/crowi.fish

サーバとのバージョン差

Crowi は self-hosted なので、crowi と接続先サーバのバージョンがずれることがあります。CLI がそれを理由にコマンドを拒否することはありません。

サーバの API が CLI の想定と違う場合は 1 行の注意を出したうえで実行を続け、そのサーバが持たない機能 (検索バックエンド未設定時の search など) は「このサーバでは利用できません」と表示します。