154 lines
8.1 KiB
Markdown
154 lines
8.1 KiB
Markdown
# 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でログインします。
|
||
続いてアカウント・接続先を確認し、ターミナルの確認コードを入力して承認します。
|
||
OIDCで認証した場合は、追加のローカルTOTPを要求しません。承認後はCLIが専用セッションを受け取ります。
|
||
OIDCプロバイダーのパスワードやトークンをターミナルに入力する必要はありません。
|
||
プロバイダー側のMFAポリシーはそのまま適用されます。パスワードログイン時のローカルTOTPも変更しません。
|
||
この追加TOTP省略はv0.3.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は後続です。
|
||
|
||
### 言語を指定して編集する
|
||
|
||
```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 pages-cli/test_pages.py
|
||
go test ./internal/server -run TestRemoteCLIHTTPIntegration -count=1
|
||
```
|
||
|
||
偽サーバと一時DBのみを使用します。本番資格情報や外部カレンダーは不要です。
|