Files
pages-cli/README.md
T
Anya Tokugawa cde94ed936
Test and release pages-cli / linux (push) Successful in 31s
Test and release pages-cli / macos (push) Skipped
feat: capture mail bodies in linked Wiki pages
2026-11-06 08:33:54 +09:00

183 lines
11 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クライアントです。
## はじめる
独立リポジトリは `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`。
### 自己署名証明書の環境に接続する
v0.2.0以降では、グローバルオプション `--insecure`(`-k`)を**コマンドの前**に指定すると、その実行中だけTLS証明書とホスト名の検証をスキップできます。既定では必ず検証し、設定・セッションにはスキップ状態を保存しません。
```sh
pages configure --origin https://wiki.example.test --username YOUR_USERNAME
pages --insecure login
pages -k task list
pages -k edit /guide --lang ja
pages -k # この対話シェルの終了まで適用
pages -k logout
```
指定のたびに標準エラーへ警告を表示します。標準出力のJSONやNeoMutt宛先候補には混ぜません。次のコマンドでは、必要なら改めて `-k` を付けます。`configure` は通信しないため `-k configure` は拒否します。
**自己署名証明書だけでなく、期限切れやホスト名不一致も許容します。通信は暗号化されますが、相手の真正性を確認できず、中間者攻撃でパスワード・Bearer・文書等を盗み見られる危険があります。** 信頼できる検証環境でのみ明示指定し、常用する環境では信頼するCAをOSへ登録して通常の検証を使ってください。遠隔HTTP、リダイレクト追従、TLS失敗時の自動再送は引き続き許可しません。
OIDCでは `pages -k login --oidc --no-browser` のように指定できます。ただし、スキップするのはCLIのHTTPS要求のみです。開いたブラウザやOIDCプロバイダーの証明書検証は変更しません。
### 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/client-contract.md)を参照してください。
## テスト
```sh
python3 -m unittest test_pages test_productivity test_distribution test_tls
```
合成サーバーと一時ディレクトリのみを使用します。TLS試験には一時証明書を生成するOpenSSLコマンドが必要です。本番資格情報や外部カレンダーは不要です。Goサーバーとの結合テストはサーバーリポジトリ側で実行します。
## タスクと連絡先
v0.3.0の `pages task from-mail` は本文を関連Wikiへ保存します(サーバーv0.8.0以降)。先に `pages task preferences --wiki-prefix /YOUR/MAIL/PATH` で閲覧制限済みの親Pathを指定してください。タスクの公開範囲とは独立して、本文はWikiの権限に従います。本文を送信しない場合は `--metadata-only` を指定します。
`pages task --help` で作成・計画・開始/終了・レポートを操作できる。
`pages contacts --help` で個人アドレス帳の検索・vCard入出力を行える。
[NeoMutt設定とタスク・連絡先の操作例](docs/neomutt.md)、[そのまま調整して使える設定例](examples/neomuttrc)を参照。これらは配布アーカイブにも同梱します。