esa-cli

esa CLI

esa（esa.io）を esa コマンド（@esaio/esa-cli）で操作する。

ここに載せるのは頻出の操作だけ。サブコマンドとオプションの全体は esa --help / esa <command> --help で確認する。

出力の形式

コマンドの結果は stdout、確認・エラーなど人間向けのメッセージは stderr に出る。 結果の形は出力先で変わり、端末では読みやすく整形され、パイプでは機械が扱いやすい テキストになる。一覧は TSV（見出し無しのタブ区切り。タブ・改行は空白に均される）、 1 件表示は key<TAB>value の行（本文を持つものは -- の後に本文が続く）。

JSON で受け取りたいときは --json <fields> を付ける。指定したフィールドだけが JSON になり、フィールド名を省いて --json だけ渡すと候補が表示される。

esa post list --json number,full_name,url   # 機械的に扱うならこれ
esa post view 123 --json body_md            # 本文だけを取り出す
esa post list --json                        # 指定できるフィールドを確認

• 作成・更新（create / update / append / prepend / archive / duplicate / rollback / attachment upload）の stdout は URL だけ。削除は stdout に何も出さない。
• esa api は API のレスポンスをそのまま JSON で返す。
• esa attachment download はファイル本体を出す（通常は --output <path> で保存）。

認証

esa auth status で確認。未認証なら esa auth login（ブラウザで OAuth 認証）。 環境変数 ESA_ACCESS_TOKEN が設定されていればそれも使える。

トークンのスコープは絞られていることがある。許可されたスコープは esa auth status で分かる。スコープ不足で失敗したら、必要なスコープを添えた esa auth login --scopes read:post,... をユーザーに促す（ブラウザ操作が要るので 勝手に実行しない）。

対象チームの解決

記事・コメント系はチームを対象に動く。チームは次の順で決まる:

1. --team <name>
2. 環境変数 ESA_TEAM
3. 既定チーム（esa config set default-team <name>）
4. 所属チームが 1 つだけならそれ
5. 複数所属で未指定ならエラー

明示するときは各コマンドに --team <name> を付ける。4 の所属チームの取得には read:team が必要なので、このスコープが無いトークンでは 1〜3 で指定する。

コマンドの構成

• esa post — 記事。list / search / view（get は別名）/ create / update / append / prepend / duplicate / rollback / revisions / backlinks / archive / delete
• esa comment — コメント。list / view（get は別名）/ create / update / delete
• esa category / esa tag / esa member — それぞれ list
• esa team — list / stats
• esa user — 認証ユーザーの情報
• esa attachment — upload / sign / download
• esa feedback — create（esa.io 運営へのフィードバック送信）
• esa config — set / get。キーは default-team と language（esa config --help で一覧）
• esa api <path> — 専用コマンドが無い API を直接叩く

よく使う操作

esa post list -q "wip:true"        # 検索クエリで絞り込み（search <query> でも同じ）
esa post view 123                  # 記事を 1 件表示（本文込み）
esa post view 123 --json body_md   # 本文だけを JSON で取り出す
esa post revisions 123             # rollback に渡すリビジョン番号を調べる

# 作成。名前に "/" を含めるとカテゴリになる（--category でも指定可）。既定は WIP
esa post create "dev/docs/新しい記事" --body "本文" --tags a,b --ship

esa post update 123 --name "改題" --ship   # 指定した項目のみ更新
esa post append 123 --body "末尾に追記"

esa comment create 123 --body "コメント本文"

esa attachment upload ./diagram.png   # stdout に添付の URL が出る

# 非対話環境での削除。ユーザーが明示的に削除を依頼し、対象を確認した後だけ実行する
esa post delete 123 --yes          # comment delete も同様