# Data CLI Remote HTTP access is a separate subproject, `pages-cli`, with the `pages` command (`pages-cli/pages`); see the [remote CLI contract and usage](ja/remote-cli.md). This local tool retains its trusted administrative database access and does not acquire Web credentials. `data/pageswiki-cli` is a local administrative data surface. It provides rsync-like one-shot transfers and an interactive Semantic Path shell. It accesses: - metadata in `pages.db`; - immutable payloads in `documents/sha256/`; - mutable Asset HEAD metadata in `assets`. The implementation uses Python's standard library only. ## Invocation modes ### One-shot ```bash data/pageswiki-cli get path:/manual/start start.html data/pageswiki-cli put start.html path:/manual/start ``` Transfers compare SHA-256 before writing. Identical content is reported as `skipped` and does not create another Revision. ### Interactive shell ```bash data/pageswiki-cli shell ``` Invoking without arguments also opens the shell when stdin is a terminal. The shell maintains a Semantic Path working directory: ```text pages:/> cd /manual pages:/manual> ls pages:/manual> view start ``` The shell uses `readline` when available: - Up/Down traverse command history. - Tab completes commands, Semantic Paths, UUIDs, Revisions, Assets, and local transfer paths. - History persists in `~/.pageswiki_history`, or the path specified by `PAGESWIKI_HISTORY`. ## Commands | Command | Behavior | | --- | --- | | `ls [PATH]` | List direct Semantic Path children | | `cd PATH` | Change shell Semantic Path | | `mv SOURCE DEST` | Move a Path and its descendants transactionally | | `view [ADDRESS]` | Display metadata and send payload to `PAGER` on a TTY | | `cat [ADDRESS]` | Write only the canonical payload to stdout | | `edit [ADDRESS]` | Edit through `EDITOR` and write back changed content | | `get ADDRESS [LOCAL]` | Download one payload | | `put LOCAL ADDRESS` | Upload a Page Revision or update an Asset HEAD | | `mget REMOTE_PATTERN [DIR]` | Download matching Semantic Paths | | `mput LOCAL_GLOB REMOTE_DIR` | Upload matching local files | | `revision [ADDRESS]` | List a Page's immutable Revision history | | `diff REV REV` | Produce a unified Document diff | | `restore REV` | Create a new Revision from an old Revision | | `link ADDRESS PATH` | Add a Semantic Path projection | | `unlink PATH [ADDRESS]` | Remove a Path projection only | | `pwd` | Show the shell Semantic Path | `put` and `mput` infer a Revision Content-Type from the local filename, with the destination Semantic Path as a fallback. Markdown input is converted to canonical HTML and loses only its `.md` / `.markdown` Semantic Path suffix. Other extensions remain part of the Path. Binary payloads are stored as immutable Documents and retain their original filename and Content-Type. | `help` | Show usage | | `exit`, `quit` | Leave the shell | `get ADDRESS -` writes to stdout and `put - ADDRESS` reads from stdin. Unlike `view`, `cat` never invokes a pager and is suitable for pipelines. ## Supported addresses | Address | Meaning | | --- | --- | | `path:/...` | Mutable Semantic Path projection | | `uuid:` | Stable Page/Object identity | | `rev:` | Immutable Revision identity | | `asset::` | Mutable Asset HEAD | A single address without a command retains the earlier inspection behavior. ## Write semantics ### Page `put` 1. Resolve `path:` or `uuid:`. 2. Create a Page UUID and Path binding if a Path does not exist. 3. Hash the input and atomically persist its immutable Document. 4. Compare with the newest Revision in `PAGESWIKI_LANG`. 5. Skip identical content or create a new Revision UUID. Page payloads must be UTF-8. Binary data belongs in an `asset:` address. ### Asset `put` 1. Hash and atomically persist arbitrary bytes. 2. Create the Asset identity if absent. 3. Skip an identical HEAD or update `head_document_hash`. ### `edit` 1. Resolve the current canonical payload. 2. Write it to a private temporary file. 3. Invoke the command in `EDITOR`. 4. Apply Page or Asset `put` semantics when the editor exits successfully. 5. Skip unchanged content and remove the temporary file. Immutable `rev:` addresses cannot be edited. ### `mv` - Semantic root cannot be moved. - A destination cannot be inside its source. - Every destination is collision-checked before mutation. - A unique temporary namespace avoids primary-key collisions. - All Path updates commit in one SQLite transaction. ### `restore` Restore never rewrites history. It reads the selected immutable Revision and creates a new Revision on the same Page with the same language. ### `link` and `unlink` These commands mutate reachability only. They never delete the Page, Revisions, or Documents. An unlinked Page may become a zombie and remains recoverable by UUID until garbage collection. ## Consistency and safety - SQLite writes use explicit transactions and a busy timeout. - The CLI initializes the additive `assets` table when absent; core schema migrations remain owned by the server. - Documents use temporary files, `fsync`, and atomic replacement. - Payload hashes are verified on every read. - Revision addresses reject writes. - rsync-like transfers skip identical hashes. - Missing canonical Documents may use the transitional SQLite body only when its SHA-256 matches. This CLI is a trusted local administrative interface and intentionally bypasses future HTTP Capability evaluation. Filesystem and database permissions define who may use it. ## Environment | Variable | Meaning | | --- | --- | | `PAGESWIKI_DATA_DIR` | Directory containing `pages.db` and `documents/` | | `PAGESWIKI_DB` | Explicit SQLite path | | `PAGESWIKI_DOCUMENTS_DIR` | Explicit Document root | | `PAGESWIKI_LANG` | Language used for selection and Page writes | | `PAGER` | Pager invoked by `view` on an interactive terminal | | `EDITOR` | Editor invoked by `edit` | | `PAGESWIKI_HISTORY` | Interactive command-history file | ## Asset metadata The normative Asset lifecycle and authorization model are defined in [`asset-model.md`](asset-model.md). The CLI is a trusted local implementation of HEAD reads and updates, not the public Asset API. | Column | Meaning | | --- | --- | | `domain_uuid` | Domain containing the mutable Asset name | | `address` | Canonical Domain-local `asset:` address | | `object_uuid` | Stable owning Object UUID | | `head_document_hash` | Current immutable Document snapshot | | `created_at_ms` | Creation timestamp | | `updated_at_ms` | HEAD update timestamp | Administrator HTTP Asset mutation is available with Domain/Campus-admin checks and ETag preconditions. The CLI remains the trusted local bulk interface.