# pages-cli **`pages` — PagesWikiをターミナルから読む、たどる、編集する。** プロファイルや言語は初回に設定し、普段のコマンドは短く保ちます。 DBに直接アクセスする `data/pageswiki-cli` とは独立したHTTPクライアントです。 ## はじめる 独立リポジトリは `https://git.anya.jp/anya/pages-cli` です。リリースのダウンロード方法とOS別の対応状況は [配布ガイド](DISTRIBUTION.md) を参照してください。 ソース版はPython 3.9以降、Linux/macOS等のUnix系環境を使用します。外部Pythonパッケージは不要です。Linux配布バイナリはPythonの別途インストール不要です。 リポジトリ内では `./pages` で実行できます。ソース版をPATHへ配置する場合: ```sh mkdir -p ~/.local/bin install -m 755 pages ~/.local/bin/pages # ~/.local/bin をPATHに含めてください。 ``` ```sh pages configure --origin https://pages.example.test --username anya pages login pages ``` パスワードと必要なTOTPは非表示プロンプトへ入力します。`pages` 単独で対話シェル、 `pages ls /manual` のように続ければワンショット操作です。 ```text pages[default]:/> cd /manual pages[default]:/manual> ls pages[default]:/manual> edit start pages[default]:/manual> exit ``` `exit` はシェルを閉じるだけです。セッションを失効させる場合は `pages logout`。 ### OIDCでログインする OIDC連携を有効にしたDomainで利用します。サーバーは **v0.3.0以降** が必要です。独立版CLI v0.1.0は対応済みです(分離前のCLIではサーバー同梱版v0.3.0以降)。 CLIのファイルだけを更新しても、v0.2.xのサーバーでは利用できません。 ```sh pages configure --origin https://pages.example.test pages login --oidc # SSH先など、ブラウザを自動で開かない場合 pages login --oidc --no-browser ``` CLIに表示されたURLを手元のPC/スマホで開き、OIDCでログインします。 続いてアカウント・接続先を確認し、ターミナルの確認コードを入力して承認します。 OIDCで認証した場合は、追加のローカルTOTPを要求しません。承認後はCLIが専用セッションを受け取ります。 OIDCプロバイダーのパスワードやトークンをターミナルに入力する必要はありません。 プロバイダー側のMFAポリシーはそのまま適用されます。パスワードログイン時のローカルTOTPも変更しません。 この追加TOTP省略にはv0.4.0以降のサーバーが必要です。v0.3.0では従来どおりTOTPを要求します。 ユーザー名の指定は省略できます。指定済みならブラウザで認証したユーザーとの一致を確認し、 不一致時は発行セッションの失効を試みて保存しません。`pages logout` 後に設定を変更できます。 リクエストは5分で失効します。Ctrl+Cはローカルの待機を終了し、未交換リクエストは期限で失効します。 他人から送られたURL・コードでは承認しないでください。通信断で交換結果が不明な場合は自動再送せず、 サーバのセッション管理で不要なセッションを確認・失効してからログインし直します。 `CLI OIDC login is unavailable on this server` は開始APIが利用できない場合の表示です。 configureの接続先URLを確認し、サーバーも対応版へ更新してください。 `OIDC login is not enabled for this domain` の場合は、対象DomainのOIDC設定を確認してください。 `--no-browser` はブラウザーの自動起動だけを抑止し、承認待ちとセッション取得は通常どおり行います。 ## 設定する ```sh pages configure # 設定を表示(トークンは表示しない) pages configure --lang auto # 表示対象の言語版を編集 pages configure list # 接続先一覧、★が既定 pages configure set --profile work --origin https://work.example.test --username anya --lang en pages configure use work # 以後はworkを指定不要 pages status pages edit /guide ``` 既定プロファイル名は `default`、新しいプロファイルの既定言語は `auto` です。 `auto` はサーバーが通常表示するRevisionの言語を取得し、その言語の最新版を編集します。 OSの言語からは推測しません。最初に名前付きプロファイルを作った場合はそれを既定とします。 言語は接続先ごとに保持します。既存設定の `und`(言語未指定)や `ja` は自動変更しません。 以前のCLIで設定済みの場合は `pages configure --lang auto` で切り替えられます。 一度だけ変更したいときは `pages edit /guide --lang auto`、`pages --profile personal --lang ja edit /guide` も使えます。 プロファイル自体は先にconfigureで登録します。引数の上書きは設定ファイルを書き換えません。 設定ファイルは `~/.config/pages-cli/config.json`(`XDG_CONFIG_HOME`対応)。 ```json { "version": 1, "default_profile": "default", "profiles": { "default": { "origin": "https://pages.example.test", "username": "anya", "lang": "auto" } } } ``` セッションは別の `sessions/PROFILE.json` に保存します。設定にパスワードやBearerを入れないでください。 ディレクトリ0700/ファイル0600を要求します。セッション保持中のorigin・username変更には 事前logoutが必要です。同じプロファイルのシェルが開いている間の設定変更はロックで拒否します。 手編集で接続先を変えても、旧セッションを新接続先に送信しません。 旧試作名 `data/pageswiki-remote` は新コマンドへの案内用ランチャーです。 旧 `~/.config/pageswiki-remote/` の資格情報は自動移行・削除しません。 新しいconfigureで接続先を登録して再ログインし、不要な旧セッションはサーバのセッション管理で失効してください。 ## 操作 | コマンド | 用途 | | --- | --- | | `ls` / `cd` / `pwd` | Semantic Pathをたどる。仮想フォルダにも移動可能 | | `cat` / `view` | 正本の出力/`$PAGER`で閲覧 | | `get ADDRESS LOCAL` | 正本をダウンロード。既存のローカルファイルは上書きしない | | `edit ADDRESS` | `$EDITOR`で編集。Wikiはauthoring Markdown、他のテキストは原文 | | `put LOCAL ADDRESS --base REVISION_UUID` | 明示した基点RevisionとのCASで更新 | | `search QUERY` | 権限付きの検索候補 | | `open ADDRESS` | ブラウザで閲覧。ブラウザ側ログインを使用 | | `status` / `logout` | 接続状態表示/セッション失効 | `pages --help`、`pages configure --help`、`pages edit --help` で引数を確認できます。 Tab補完、上下キーのプロセス内履歴に対応。複雑な引用位置の補完、Ctrl+Pのfuzzy UIは後続です。 ### 言語を指定して編集する `auto` 言語選択と未作成言語版の編集は、独立版CLI v0.1.0で利用できます(分離前はサーバー同梱版v0.4.0以降)。 ```sh pages edit /guide --lang auto # 表示される言語の最新版を編集 pages edit /guide --lang ja # 日本語版。未作成なら既存内容から開始 pages edit /guide --lang en # 英語版。未作成なら既存内容から開始 ``` 編集開始時に対象言語を表示します。指定言語のRevisionがない場合は、表示中の版の内容を 下書きとして `$EDITOR` を開き、変更を保存するとその言語の最初のRevisionを作ります。 自動翻訳ではありません。元の言語版は変更せず、編集せずに閉じた場合は何も作成しません。 同じ言語版が先に作成された場合も、競合として保存を止めます。 対応範囲は既存Pageの更新と新規言語版の作成です。新規Path/Page作成、バイナリ更新は未実装です。 競合や通信断で自動上書きせず、ローカル原稿を保持します。HTTPS必須(開発用loopbackのみHTTP可)。 詳しいURI・保存・安全性の契約はサーバーリポジトリの `docs/design/ja/remote-cli.md` にあります(同リポジトリへのアクセス権が必要です)。 ## テスト ```sh python3 -m unittest test_pages test_productivity test_distribution ``` 合成サーバーと一時ディレクトリのみを使用します。本番資格情報や外部カレンダーは不要です。Goサーバーとの結合テストはサーバーリポジトリ側で実行します。 ## タスクと連絡先 `pages task --help` で作成・計画・開始/終了・レポートを操作できる。 `pages contacts --help` で個人アドレス帳の検索・vCard入出力を行える。 neomutt設定と操作例はサーバーリポジトリの `docs/operations/neomutt-tasks.md` を参照。