Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming. Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
6.3 KiB
Data CLI
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
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
data/pageswiki-cli shell
Invoking without arguments also opens the shell when stdin is a terminal. The shell maintains a Semantic Path working directory:
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 byPAGESWIKI_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:<uuid> |
Stable Page/Object identity |
rev:<uuid> |
Immutable Revision identity |
asset:<type>:<name> |
Mutable Asset HEAD |
A single address without a command retains the earlier inspection behavior.
Write semantics
Page put
- Resolve
path:oruuid:. - Create a Page UUID and Path binding if a Path does not exist.
- Hash the input and atomically persist its immutable Document.
- Compare with the newest Revision in
PAGESWIKI_LANG. - Skip identical content or create a new Revision UUID.
Page payloads must be UTF-8. Binary data belongs in an asset: address.
Asset put
- Hash and atomically persist arbitrary bytes.
- Create the Asset identity if absent.
- Skip an identical HEAD or update
head_document_hash.
edit
- Resolve the current canonical payload.
- Write it to a private temporary file.
- Invoke the command in
EDITOR. - Apply Page or Asset
putsemantics when the editor exits successfully. - 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
assetstable 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. 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.