crowi CLI

crowi は HTTP 越しに自分の権限で wiki を操作するエンドユーザー向け CLI です。インストールとログインの手順は CLI (コマンドライン) を参照してください。

グローバルフラグ

どのコマンドでも、コマンド名の前後どちらにも置けます。

フラグ	意味
`-p, --profile <alias>`	保存済みのプロファイルを名前で選ぶ
`--url <baseUrl>`	プロファイルを使わずサーバを直接指定する
`--token <accessToken>`	トークンを直接渡す (個人アクセストークンなど)
`--json`	人間向け表示のかわりに構造化した JSON を出力する (出力する項目はコマンドごとに異なる)
`-q, --quiet`	進捗表示 (stderr) を抑止する
`--help` / `--version`	ヘルプとバージョンを表示する

コマンド

必要なスコープは HTTP API のスコープカタログの語です。既定のログインスコープは pages:read pages:write で、crowi login --scope を指定するとこの既定値は置き換わるので、ページ操作も使う場合は pages:read pages:write も並べて指定します。

コマンド	用途	固有のフラグ	必要なスコープ
`login [url]`	サーバにサインインしてプロファイルに保存する	`--device` / `--token <pat>` / `--scope <scopes>`	—
`logout`	トークンを失効・削除する	—	—
`whoami`	サインイン中のユーザーと有効なスコープを表示する	—	—
`profiles`	保存済みのプロファイルを一覧する (通信なし)	—	—
`profiles use <alias>`	既定で使うプロファイルを切り替える (通信なし)	—	—
`completion <shell>`	シェル補完スクリプトを出力する	—	—
`open <path-or-id>`	ブラウザでページを開く	`--print`	—
`search <query>`	全文検索する	`--tree <path>` / `--type <type>` / `--page <n>` / `--limit <n>` / `--format <mode>` / `--template <tpl>`	`pages:read`
`get <path-or-id>` (別名 `cat`)	ページ本文を保存されたとおりに標準出力へ書き出す (本文が改行で終わらないときだけ改行を 1 つ足す)	`--revision <id>`	`pages:read`
`ls [path]`	パス配下の子ページを一覧する	`--format <mode>` / `--template <tpl>`	`pages:read`
`diff <path-or-id>`	ページの最新の本文とローカルのファイルを比べる。末尾の改行の数は無視し、違えば unified diff を出して `1` で終わる	`-f, --file <path>`	`pages:read`
`recent`	最近更新されたページを新しい順に一覧する	`--prefix <path>` / `--limit <n>` / `--offset <n>` / `--format <mode>` / `--template <tpl>`	`pages:read`
`create <path>`	ページを作成する	`-m, --message <text>` / `-f, --file <path>` / `--stdin` / `--editor <bin>` / `--grant <n>` / `--type <kind>`	`pages:write`
`edit <path>`	エディタで対話編集する (artifact ページでも使え、`.html` の一時ファイルを開く)	`--editor <bin>` / `--force`	`pages:write`
`update <path>`	本文を非対話で置き換える	`-m, --message <text>` / `-f, --file <path>` / `--stdin` / `--force` / `--type <kind>`	`pages:write`
`mv <old> <new>`	ページを移動 / リネームする	`--no-redirect` / `--recursive`	`pages:write`
`rm <path>`	ページを削除する	`--completely` / `--force`	`pages:write`
`watch status <path-or-id>`	ウォッチしているかを表示する	—	`pages:read`
`watch subscribe <path-or-id>`	ウォッチを開始する	—	`pages:write`
`watch unsubscribe <path-or-id>`	ウォッチをやめる	—	`pages:write`
`comment list <path-or-id>`	コメントを一覧する	—	`comments:read`
`comment add <path-or-id>`	コメントを投稿する	`-m, --message <text>` / `-f, --file <path>`	`comments:write`
`attach list <path-or-id>`	添付ファイルを一覧する (行頭に添付 ID)	—	`attachments:read`
`attach add <path-or-id> <file>`	添付ファイルをアップロードする	—	`attachments:write`
`attach download <id>`	添付ファイルを取り出す	`-o, --output <file>`	`attachments:read`
`bookmark list`	ブックマークを一覧する	`--limit <n>` / `--offset <n>`	`bookmarks:read`
`bookmark add <path-or-id>`	ブックマークに追加する	—	`bookmarks:write`
`bookmark remove <path-or-id>`	ブックマークから外す	—	`bookmarks:write`

mv と rm (--completely を除く) は、実行のたびに鍵を自動生成してリクエストに付け、通信の都合で同じリクエストがサーバへ二重に届いても 1 回しか適用されないようにします。利用者が鍵を意識したり指定したりする必要はありません。ただし、コマンドを自分でもう一度実行するのは別の操作として扱われ、重複排除の対象になりません。rm /some/page を 2 回実行すれば、削除も 2 回試みられます。rm --completely も鍵は送りますが、hard delete の経路はその鍵を読まないため、この保護の対象外です。

recent

crowi recent [--prefix <path>] [--limit N] [--offset N] は、閲覧できるページを最終更新の新しい順にフラットに表示します。検索語も検索プラグインも不要です。1 行は更新イベントではなくページの現在の状態で、同じページを何度更新しても 1 行です。列は path、updatedAt (UTC)、lastUpdateUser (作成者ではなく最後の更新者)、_id の順です。

crowi recent
crowi recent --limit 20 --json
crowi recent --prefix /team/ --limit 20 --offset 20
crowi recent --prefix /team --format table
crowi recent --template '{{path}}\t{{updatedAt}}\t{{lastUpdateUser.username}}\t{{_id}}'

--limit は 1〜100 (既定 50)、--offset は 0〜2147483647 (既定 0) で、どちらも 10 進数字だけを受け付けます。不正な値は通信の前に終了コード 6 で拒否されます。
--prefix は保存されたパスに対する、大文字小文字を区別するリテラルの前方一致です。/team は /team と /team/ と /teamwork に、/team/ は /team/ とその配下に一致します (/team は含みません)。先頭の / がなければ補われ、--prefix / は prefix なしと同じです。空文字は拒否されます。
一覧はライブです。--offset で順に取得する間にページが更新されると、重複や取りこぼしが起こり得ます。同じ更新日時のページの順序は決まっていません。cursor や全件の自動巡回はありません。
一覧の行にはページの本文が含まれません。--json の revision に body は無く、--template の {{revision.body}} は空になります。本文は crowi get <path> で取得します。
--json はサーバの応答全体をそのまま出力します。--template なしの --format template は元のページから同じ 4 項目を引くので、lastUpdateUser は JSON オブジェクトになります。名前は {{lastUpdateUser.username}} で取り出します。
--prefix は path_prefix に対応したサーバが必要です。応答で prefix の適用を確認できないと、標準出力には何も書かず、server did not confirm literal prefix filtering; upgrade Crowi and retry を出して終了コード 7 で終わります。--prefix なし (または --prefix /) なら古いサーバでも使えます。

出力フォーマット

search / ls / recent は --format / --template で出力を整形できます。

値	出力
`--format human`	既定の人間向け表示
`--format table`	ヘッダ付きの整列カラム
`--format json`	グローバルの `--json` と同じ JSON
`--format template`	レコードごとに 1 行のテンプレート出力
`--template '<tpl>'`	テンプレートモード。`{{field}}` をレコードの値で置換する (`--format template` を含意)

{{field}} はドット区切り ({{page.path}}) でネストを辿り、欠落フィールドは空文字になります。テンプレート中の \t / \n はタブと改行に展開されます。進捗と警告はすべて stderr に出るため、--json の標準出力はスクリプト用にクリーンなままです。

終了コード

コード	意味
`0`	成功
`1`	一般エラー / 通信失敗 (`diff` ではページとファイルが異なる)
`2`	未サインイン (`crowi login` が必要)
`3`	スコープ不足 (`--scope` を足して再ログインする)
`4`	対象が存在しない
`5`	編集競合 (`--force` で上書きできる)
`6`	引数不正 (artifact の書き込み拒否も含む — `400` / `413` / `422` はいずれもここに落ちる)
`7`	サーバ利用不可 / 機能が無効 (`recent --prefix` で、サーバが prefix の適用を確認できなかった場合も含む)

artifact ページ

create / update は --type <kind> (markdown または artifact) でその書き込みのページ種別を宣言できます。省略するとサーバの既定 (create は markdown、update は現在の種別) が使われます。種別がファイルの拡張子や本文の中身から推測されることはありません。edit は artifact ページでも markdown ページと同じように使え、ページが既に持っている種別をそのまま保ちます。違いは .md ではなく .html の一時ファイルを開く点だけで、エディタのシンタックスハイライトが本文に合ったものになります。

artifact の書き込みが拒否されると (400 / 413 / 422、いずれも終了コード 6)、サーバの固定メッセージに規則の識別子と理由が付き、規則が該当箇所を特定できるときは target も付きます。

crowi: This script type is not allowed in an artifact page. (AI-R13 / SCRIPT_TYPE_FORBIDDEN)
target: script[type]