workpads-cli

The Workpads command-line interface. Creates, edits, shares, and manages workpad records locally from the terminal.

Version 0.2+ uses pads-v1 (#1pa/) via @workpads/codec. Share URLs match Workpads KaiOS and the normative standard (codec.md §5).

Cross-repo process:workpadskaios/system/project-process.md

---

What is it?

A Node.js command-line interface for creating, editing, sharing, and managing Workpads job records from the terminal. Produces pads-v1 encoded share URLs compatible with Workpads KaiOS and any other Workpads client. The reference implementation of the Workpads CLI contract defined in the normative standard.

The Problem

Teams using Workpads on KaiOS devices need a desktop/server counterpart — a way to create records in scripts, import shared links, inspect record contents, and integrate Workpads into automated workflows. A phone-only system cannot serve operators who also work at terminals, write scripts, or need to process records in bulk.

How it Works

A single Node.js script (workpads.js) with no external runtime dependencies. Commands cover the full record lifecycle: create, edit, render, share, import, list, export, delete. Share links use pads-v1 (#1pa/) via @workpads/codec — the same encoding as the KaiOS app. Records stored locally in .workpads/records.json.

Current Status

v0.2.1 — pads-v1 encoding active. Full CRUD command surface implemented. Binary file export (.wpf) supported. Browser service (local HTTP UI) operational. v0.3 will align the command surface with the GatewayService contract for multi-device sync.

The Vision

The terminal entry point to the Workpads ecosystem. As Workpads matures toward a gateway/sync model, the CLI will serve as the primary scripting and automation surface — letting developers, operators, and integrators interact with Workpads records without a UI.

Industry Context

Field service and trade businesses increasingly run hybrid workflows — mobile workers on feature phones, supervisors on laptops. The CLI bridges these contexts: records created on a KaiOS device can be imported and processed at a workstation, and vice versa, over a URL that fits in an SMS.

---

What Is a Workpad?

A workpad is a portable job record structured around the PADS model:

Section	Fields
Process	job, customer, date, location
Actions	Repeatable step items — [{ title, notes }]
Details	start_time, end_time, meeting_time, customer_phone, worker
Story	story, details (narrative and technical notes)

A workpad lives locally (in .workpads/records.json), can be rendered to the terminal, and can be shared as a compact URL — readable by any Workpads client.

---

Install

cd workpads-cli
npm install

Node.js >= 14 required. No external runtime dependencies beyond Node's built-in zlib module.

Run

node ./workpads.js <command>

Or after npm install:

npx workpads <command>

---

Field Reference

These are all recognised fields on the svc-basic template (v1):

Field	Type	Description
job	string	Job title — required. Displayed as the primary record identifier.
customer	string	Customer or client name.
date	string	Date of work (ISO 8601, e.g. 2026-04-27).
location	string	Site address or location descriptor.
start_time	string	Work start time (free text, e.g. 09:00).
end_time	string	Work end time.
meeting_time	string	Scheduled meeting/arrival time.
customer_phone	string	Customer contact number.
worker	string	Name of the person performing the work.
details	string	Technical notes, materials, or observations.
story	string	Narrative summary — what happened, in plain language.
actions	array	List of { title, notes } step items.

---

URL Encoding Format (v0.2+ — pads-v1)

Share links use:

https://workpads.me/p#1pa/<base64url>

Produced by @workpads/codecencode(): pads-v1 binary frame, fflate.deflateSync level 9, base64url (no padding). See workpads-file-format.md for .wpf binary export.

Legacy (pre-v0.2): JSON + deflate-raw encoding is no longer used by this CLI. Old URLs may still decode via codec legacy routes.

Historical v0.x JSON encoding (obsolete)

The pre-v0.2 share link used:

https://workpads.me/new#<payload>

1. Record fields serialised as compact JSON short keys
2. Compressed with zlib.deflateRawSync
3. Encoded as base64url (URL-safe, no padding)

This produced links of approximately 80-200 characters for a typical job record.

---

Commands

Record Operations

Create a record:

node ./workpads.js create --template svc-basic --variant plain \
--business biz_001 \
--set process.job="Replace faucet" \
--set process.date="2026-04-27"

Edit a record:

node ./workpads.js edit --record loc_000001 \
--add-action "Arrive|Inspect site" \
--add-action "Install|Replace fixture" \
--set details="Bring standard tools"

Render a record in the terminal:

node ./workpads.js render --record loc_000001
node ./workpads.js render --record loc_000001 --json

Share a record (produces URL):

node ./workpads.js share --record loc_000001
node ./workpads.js share --record loc_000001 --base-url "https://workpads.me/new"

Import a shared link:

node ./workpads.js import --url "https://workpads.me/new#<payload>"echo"https://workpads.me/new#<payload>"| node ./workpads.js import

Round-trip in one block:

LINK=$(node ./workpads.js share --record loc_000001 | tr -d '\n')
node ./workpads.js import --url "$LINK"

List all records:

node ./workpads.js list
node ./workpads.js list --json

Default columns: recordId, variant, storageMode, shareBytes, job.

Export a record to file:

node ./workpads.js export --record loc_000001 --out ./exports/loc_000001.json

Delete a record:

node ./workpads.js delete --record loc_000001

Dashboard (size statistics):

node ./workpads.js dashboard
node ./workpads.js dashboard --json

Template Operations

Templates define the field schema and variant rules for record types.

Validate a template:

node ./workpads.js template:validate --file ./templates/svc-basic.kv --format kv
node ./workpads.js template:validate --file ./templates/svc-basic.yaml --format yaml

Compile to runtime JSON:

node ./workpads.js template:compile \
--file ./templates/svc-basic.yaml --format yaml \
--out ./templates/runtime/svc-basic.v1.json

Show compiled template:

node ./workpads.js template:show --template svc-basic

Storage Policy Operations

Storage policies let a business set default persistence rules (ephemeral vs. stored) with optional TTL and per-record overrides.

node ./workpads.js storage:set --business biz_001 --default ephemeral --ttl-hours 24 --allow-override true
node ./workpads.js storage:get --business biz_001
node ./workpads.js storage:resolve --business biz_001 --override stored

Aliases: policy:get, policy:set, policy:resolve map to the storage:* commands.

Comment Operations

Comments are appended to records locally and are not encoded into share links.

node ./workpads.js comment:add --record loc_000001 --text "Arrived on site" --name "Alex"
node ./workpads.js comment:list --record loc_000001
node ./workpads.js comment:delete --record loc_000001 --index 0

Browser Service

Starts a local HTTP server with an embedded web UI:

node ./workpads.js browser
node ./workpads.js browser --port 8787
node ./workpads.js browser --auto-port true
node ./workpads.js browser --ui latest # default UI
node ./workpads.js browser --ui v1 # pinned simple fork snapshot
node ./workpads.js browser:status
node ./workpads.js browser:stop

Help and Role Flows

node ./workpads.js howto
node ./workpads.js howto --role owner
node ./workpads.js howto --role dispatcher
node ./workpads.js howto --role receiver

---

Data Storage

Records are stored locally in .workpads/records.json relative to the working directory. Storage policies are stored in .workpads/storage-policies.json.

Record IDs use the format loc_000001, loc_000002, etc. (sequential). These IDs are local and not transmitted in share links — only the field data is encoded.

---

Templates

The templates/ folder contains:

File	Format	Purpose
svc-basic.kv	Key-value	Canonical human-readable template definition
svc-basic.yaml	YAML	Alternative source format for compile
runtime/svc-basic.v1.json	JSON	Compiled runtime schema loaded by the CLI

The svc-basic template is the first-party template for field service work records. It supports one variant: plain.

---

Roadmap

v0.2 — bitpad-v1 encoding upgrade:

• Replace JSON + deflateRaw with the bitpad-v1 binary frame codec
• Share links will be 30-50% shorter and fully compatible with Workpads KaiOS v0.1+
• Encoding will be provided by @workpads/codec (the workpads-codec package)

v0.3 — Gateway compatibility:

• Align CLI command surface with the Workpads GatewayService contract
• Enable multi-device sync and server-backed record storage via gateway endpoint

---

Related Repos

Repo	Description
workpads/	Original architecture documents, protocol specs, template source files
workpads-codec/	@workpads/codec npm package — bitpad-v1 encoder/decoder for Node.js
workpadskaios/	Workpads mobile app for KaiOS 3.x devices
workpads-standard/	Formal Workpads Standard — normative specification