Edit installed documents

Work on the same document as the person using the app. Named commands run the app’s authored actions; apply and batch edit fields directly. Both go through the Rust owner, save accepted edits, and update an open window. Edit ▸ Undo includes agent edits.

This walkthrough uses the bundled Quick Checklist, with Bun and the Mac app installed. Run bunx @hitslop/pop as below, or install globally and use pop. Responses show example paths, versions and shortened row IDs; use the values your own CLI prints. JSON is compacted in a few places for readability.

1. Create and open your own copy

Templates are immutable. Create a writable document at a new path:

bunx @hitslop/pop create --from quick-checklist --output Today.pop

/Users/you/Documents/Today.pop

bunx @hitslop/pop open Today.pop

/Users/you/Documents/Today.pop

Keep this terminal in the directory containing Today.pop, or use its full quoted path. Opening the window needs the Mac app; reading and editing a file also work on Linux.

2. Discover fields and actions

bunx @hitslop/pop describe Today.pop

Response: fields, command arguments, and current values

Quick Checklist: A blush pocket utility for capturing, finishing, and filing short task lists.
Version: 000000000000000100000077

Fields
  ["tasks"]: list (insert, remove, move, replace)
  ["tasks",{"id":"$id"}]: object (replace)
  ["tasks",{"id":"$id"},"archived"]: boolean (set) — Filed away from the to-do list.
  ["tasks",{"id":"$id"},"done"]: boolean (set)
  ["tasks",{"id":"$id"},"text"]: text (set)
  ["title"]: text (set) — The title shown in the window.

Commands (pop call PATH NAME --args JSON)
  Arguments accept only the listed fields.

  addTask — Add an unfinished task and return its stable row ID.
    text: string (required)

  archiveFinished — File every completed task and return the number filed.
    No arguments. Pass --args '{}'.

  removeTask — Remove a task from the checklist.
    task: string (required) — The task's $id.

  restoreTask — Return a filed task to the active list, unfinished.
    task: string (required) — The task's $id.

Value (rows retain their $id)
{
  "tasks": [
    {
      "$id": "starter-1",
      "archived": false,
      "done": true,
      "text": "Send the first draft"
    },
    {
      "$id": "starter-2",
      "archived": false,
      "done": false,
      "text": "Take a walk without my phone"
    },
    {
      "$id": "starter-3",
      "archived": false,
      "done": false,
      "text": "Make a little room for the weekend"
    }
  ],
  "title": "Little things, today"
}

describe lists the commands actually stored in this document. Add --json for a structured description for tools. A different app may expose different actions, or none.

3. Run the app’s addTask action

bunx @hitslop/pop call Today.pop addTask --args '{"text":"Book train"}'

{"result":{"id":"train"},"ids":["train"]}

The real ID will differ. The command returns its result and any inserted IDs. Its argument validation and behavior are the same as the app’s action; a refusal applies nothing. A successful call is one atomic edit and one undo step.

Read the document to see the new task alongside the starter tasks:

bunx @hitslop/pop get Today.pop

{
  "tasks": [
    {
      "$id": "starter-1",
      "archived": false,
      "done": true,
      "text": "Send the first draft"
    },
    {
      "$id": "starter-2",
      "archived": false,
      "done": false,
      "text": "Take a walk without my phone"
    },
    {
      "$id": "starter-3",
      "archived": false,
      "done": false,
      "text": "Make a little room for the weekend"
    },
    {
      "$id": "train",
      "archived": false,
      "done": false,
      "text": "Book train"
    }
  ],
  "title": "Little things, today"
}

4. Edit a field directly

Replace train with the $id returned above. Row IDs stay stable even if a list is reordered.

bunx @hitslop/pop apply Today.pop --op '{"type":"set","path":["tasks",{"id":"train"},"done"],"value":true}'

{"ids":[]}

The box checks itself in the open window. An empty ids list means no rows were inserted; it does not mean no edit happened. You can also apply several operations atomically:

bunx @hitslop/pop batch Today.pop --ops '[{"type":"set","path":["tasks",{"id":"train"},"done"],"value":false},{"type":"set","path":["tasks",{"id":"train"},"archived"],"value":false}]'

{"ids":[]}

This restores the task to unfinished and unfiled. If one operation is invalid, none apply.

5. Check the result

bunx @hitslop/pop get Today.pop

Response excerpt (the other tasks and title are still present):

{"$id":"train","archived":false,"done":false,"text":"Book train"}

Check get before retrying after an uncertain outcome, especially an insertion. Errors go to stderr with a nonzero exit status. For example, an empty task is refused:

bunx @hitslop/pop call Today.pop addTask --args '{"text":""}'

Error: Enter a task. (refused)
Not applied.

The CLI routes to the open document’s owner or edits a closed document without loading its interface. It never bypasses a busy writer. There is no editable data.json file; get is a read-only snapshot, and templates’ initial values do not change saved work.

A text set replaces the field. When you rewrite text you read and someone may be typing in the open window, you can also pass the text you read as from: the edit then changes the field from that text and keeps anything typed since.

bunx @hitslop/pop apply Today.pop --op '{"type":"set","path":["title"],"value":"Little things, this week","from":"Little things, today"}'