Files
pages/pages-cli/README.md
T
Anya Tokugawa 60f5fb1881
Build and publish container images / images (push) Successful in 14m39s
Release container images / release (push) Successful in 25s
Add OIDC browser approval and PKCE session handoff for pages CLI
2026-11-01 20:26:45 +09:00

137 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# pages-cli
**`pages` — PagesWikiをターミナルから読む、たどる、編集する。**
プロファイルや言語は初回に設定し、普段のコマンドは短く保ちます。
DBに直接アクセスする `data/pageswiki-cli` とは独立したHTTPクライアントです。
## はじめる
Python 3.9以降、Linux/macOS等のUnix系環境を使用します。外部Pythonパッケージは不要です。
リポジトリ内では `./pages-cli/pages` で実行できます。PATHへ配置する場合:
```sh
mkdir -p ~/.local/bin
install -m 755 pages-cli/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で利用します。サーバーと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でログインします。
続いてアカウント・接続先を確認し、ターミナルの確認コードを入力して承認します。
ローカルTOTPを設定済みならTOTPも必要です。承認後はCLIが専用セッションを受け取ります。
OIDCプロバイダーのパスワードやトークンをターミナルに入力する必要はありません。
ユーザー名の指定は省略できます。指定済みならブラウザで認証したユーザーとの一致を確認し、
不一致時は発行セッションの失効を試みて保存しません。`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 ja # 現在の既定接続の編集言語
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`、既定言語は `und`(言語未指定)です。OSや表示言語から
書き込み先の言語を推測しません。最初に名前付きプロファイルを作った場合はそれを既定とします。
言語は接続先ごとに保持し、編集時はその言語の既存Revisionを使用します。
一度だけ変更したいときは `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": "und"
}
}
}
```
セッションは別の `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は後続です。
初期版は既存Page・既存言語の更新まで。新規作成、バイナリ更新は未実装です。
競合や通信断で自動上書きせず、ローカル原稿を保持します。HTTPS必須(開発用loopbackのみHTTP可)。
詳しいURI・保存・安全性の契約は[設計書](../docs/design/ja/remote-cli.md)を参照してください。
## テスト
```sh
python3 pages-cli/test_pages.py
go test ./internal/server -run TestRemoteCLIHTTPIntegration -count=1
```
偽サーバと一時DBのみを使用します。本番資格情報や外部カレンダーは不要です。