8.9 KiB
pages-cli
このディレクトリはサーバーのHTTP結合テスト用スナップショットです。CLIの配布・新規開発・利用手順の正本は公開pages-cliリポジトリへ移転しました。NeoMutt連携ガイドとクライアント契約も独立側を参照してください。
pages — PagesWikiをターミナルから読む、たどる、編集する。
プロファイルや言語は初回に設定し、普段のコマンドは短く保ちます。
DBに直接アクセスする data/pageswiki-cli とは独立したHTTPクライアントです。
はじめる
Python 3.9以降、Linux/macOS等のUnix系環境を使用します。外部Pythonパッケージは不要です。
リポジトリ内では ./pages-cli/pages で実行できます。PATHへ配置する場合:
mkdir -p ~/.local/bin
install -m 755 pages-cli/pages ~/.local/bin/pages
# ~/.local/bin をPATHに含めてください。
pages configure --origin https://pages.example.test --username anya
pages login
pages
パスワードと必要なTOTPは非表示プロンプトへ入力します。pages 単独で対話シェル、
pages ls /manual のように続ければワンショット操作です。
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のサーバーでは利用できません。
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 はブラウザーの自動起動だけを抑止し、承認待ちとセッション取得は通常どおり行います。
設定する
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対応)。
{
"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 言語選択と未作成言語版の編集は、v0.4.0以降のCLIで利用できます。
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・保存・安全性の契約は設計書を参照してください。
テスト
python3 pages-cli/test_pages.py
go test ./internal/server -run TestRemoteCLIHTTPIntegration -count=1
偽サーバと一時DBのみを使用します。本番資格情報や外部カレンダーは不要です。
タスクと連絡先
pages task --help で作成・計画・開始/終了・レポートを操作できる。
pages contacts --help で個人アドレス帳の検索・vCard入出力を行える。
neomutt設定と操作例を参照。