CLI workflows

Use the CLI yourself or let your coding agent run it. Start with an authoring project to change an app, or a writable .slop document to work with its data.

Responses below use example paths and compact JSON. Versions, timings, generated IDs, installed templates and palettes vary. Larger responses are explicitly marked as excerpts. Shell commands such as cd succeed without printing a response.

Choose how to run commands

Install Bun 1.4.2 or newer. To open document windows, install the hitSlop Mac app. The examples below use bunx hitslop.

Entry point	When to use it
bunx hitslop COMMAND	Run the authoring CLI without a global install.
slop COMMAND	After bun install -g hitslop, with Bun’s bin directory on your PATH.

Use bunx or slop for the examples below. Authoring builds, registering, browser preview, document creation and document edits run on macOS or Linux. On both platforms the CLI also renders template artwork and exports closed documents as PNG/PDF itself. Opening a window uses the installed Mac app, which need not already be running.

The npm package includes its document engine, which does that rendering. open finds the Mac app automatically in /Applications or ~/Applications.

Append --help to any command to see its arguments.

Local browser copies (Chrome beta)

slop open --browser ./MyDocument.slop
slop open --browser

Example responses (copy and import IDs vary):

http://127.0.0.1:41238/?copy=COPY_ID#import=IMPORT_ID
Local browser host is running. Keep this terminal open; Ctrl-C stops it.

Opening the list prints http://127.0.0.1:41238. The host message appears only when this invocation starts the host; one that reuses it prints the URL and exits.

The first command opens an independent copy in desktop Google Chrome. The second opens your saved browser copies. Keep the host terminal running; Ctrl-C stops it. Later invocations reuse the same host. No account or server upload is involved.

Edits autosave in this browser profile on this device. Download .slop includes the current app, data, theme and referenced attachments for opening in the desktop client. The original file stays unchanged. Browser storage can be cleared or evicted: download copies you want to keep. Reload requires the local host to be running.

The first version supports Chrome on desktop. Safari, private browsing, mobile and shareable hosted links are deferred. Fullscreen appears for apps declaring fullscreenable; Keep awake is a separate, initially off toggle.

Create, preview, and register an app

bunx hitslop init weekend-kit
cd weekend-kit
bun install
bun run check
bun run dev

Expected terminal responses (build-tool progress omitted):

Command	Response
init weekend-kit	After the brief and author questions: Created /Users/you/weekend-kit. Run bun install in that directory, then bun run dev. Then choose an agent.
cd weekend-kit	No output on success.
bun install	Bun’s dependency installation summary; package counts and timing vary.
bun run check	svelte-check found 0 errors and 0 warnings for a valid starter.
bun run dev	Disposable preview: http://localhost:5173/ (port may differ); the process stays running.

init asks what you want to build and who the author is. The agent you launch next sets the app’s title, description, and categories in slop.ts to match what it builds; you can edit them there anytime. Your description is saved in BRIEF.md alongside the checklist starter and local agent guidance.

At the end, choose which agent CLI should build your slop. The picker offers detected Codex, Claude Code, Gemini CLI, and OpenCode installations. Choose Other CLI… for Grok or another installed tool: enter its executable name or path, then its prompt option (leave blank if it accepts a positional prompt). The agent opens in the new project and is asked to read the brief and hitSlop guidance before implementing your app. It uses its existing account, model, and permission settings.

Choose Finish without launching to work manually. If an agent fails or you cancel the launch, your project remains ready to use. No agent is installed automatically.

For an agent or script that is already running, create the project without another interactive session:

bunx hitslop init budget-book --yes \
  --brief 'Track spending by category with a monthly summary.' \
  --title 'Budget Book' \
  --category finance --category personal --author Jordan \
  --description 'A simple monthly spending tracker.'

Response (with your chosen destination):

Created /Users/you/budget-book. Run bun install in that directory, then bun run dev.

This invocation has no interactive questions or agent launch.

Flags set metadata explicitly; --brief and --author also skip their questions. --yes, CI, and non-interactive terminals never prompt or launch an agent. Missing values default to the directory name, productivity, Anonymous, and A hitSlop mini app.; an omitted brief uses that description. The wizard initializes the explicit slug from the directory name: 2–64 lowercase letters or digits, separated by single hyphens. Metadata is validated before files are created, and an existing destination is never overwritten.

Read slop.ts, AGENTS.md, and BRIEF.md before editing. Preview data resets on refresh, and an invalid edit shows a diagnostic until you fix it. Vite watches source changes. Component and CSS updates preserve accepted edits; a change to slop.ts, schema.ts, commands.ts, their dependencies (including skin or artwork), or the role inventory resets disposable state.

Stop the preview, then package the app and add it to your local catalog:

bun run build
bun run register

Responses, respectively (additional build progress omitted):

/Users/you/weekend-kit/dist/weekend-kit.slop
/Users/you/.hitslop/templates/weekend-kit.slop

Build writes dist/weekend-kit.slop on macOS or Linux, with Finder artwork rendered on either platform. Register builds it the same way and adds it to the Mac app’s template catalog. Existing documents keep their app version.

From outside the project, the equivalent commands take its source directory: slop check ./weekend-kit, slop dev ./weekend-kit --port 5174 (the preview port defaults to 5173), slop build ./weekend-kit, and slop register ./weekend-kit. See create your first slop for the authoring tutorial.

Create and open a writable document

In the Mac app, choose a template and select Create. For the terminal equivalent, run these commands from your authoring project:

bunx hitslop create --from dist/weekend-kit.slop --output "$HOME/Documents/Weekend.slop"
bunx hitslop open "$HOME/Documents/Weekend.slop"

Both commands print the same resolved path after success:

/Users/you/Documents/Weekend.slop

Create makes a new document with the template’s starting data; choose a destination that does not already exist, and .slop is added if you leave it off. Open launches it in hitSlop. Both print the document’s path. Keep writable documents out of synced folders such as iCloud Drive.

To start from a template in the Mac app’s catalog instead, list them and pass a slug to --from:

bunx hitslop templates
bunx hitslop create --from weekend-kit --output "$HOME/Documents/Weekend.slop"

The templates response is a catalog object. Example excerpt:

{
  "templates": [
    {
      "slug": "weekend-kit",
      "title": "Weekend Kit",
      "source": "installed",
      "path": "/Users/you/.hitslop/templates/weekend-kit.slop"
    }
  ]
}

The following create prints /Users/you/Documents/Weekend.slop. Run one of the two creation examples, or choose a different output path for a second copy.

templates prints each template’s slug, title, description, categories, path and source: bundled with the app, or installed by register. If you register a template with the same slug as a bundled one, the slug names yours.

Read and edit data

For a complete numbered example with every response, follow edit a Checklist document. It creates a writable copy, discovers its commands, calls addTask, reads the returned row, and changes its done field with apply.

For an existing document, replace My.slop with its path. Quote paths containing spaces:

bunx hitslop describe My.slop

Example excerpt from a Checklist response:

Commands (slop 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)

describe marks arguments as required or optional and shows their defaults, choices, bounds and descriptions when present. It also prints fields, operations, a version, and current values. Add --json for a structured description with full argument JSON Schemas. Run an action that it lists:

bunx hitslop call My.slop addTask --args '{"text":"Buy coffee"}'

{ "result": { "id": "example-task-id" }, "ids": ["example-task-id"] }

The real ID differs. Commands use the app’s authored behavior and apply as one undo step. A command without a return value reports "result": null.

Inspect the stored descriptor separately:

bunx hitslop schema My.slop

Response excerpt for Checklist’s title field:

{ "kind": "text", "description": "The title shown in the window." }

Read saved values:

bunx hitslop get My.slop

Response excerpt from its tasks array:

{ "$id": "example-task-id", "archived": false, "done": false, "text": "Buy coffee" }

For a direct edit, use that row’s actual ID:

bunx hitslop apply My.slop --op '{"type":"set","path":["tasks",{"id":"example-task-id"},"done"],"value":true}'

{ "ids": [] }

Or group edits in one atomic batch:

bunx hitslop batch My.slop --ops '[{"type":"set","path":["tasks",{"id":"example-task-id"},"done"],"value":false},{"type":"set","path":["tasks",{"id":"example-task-id"},"archived"],"value":false}]'

{ "ids": [] }

ids lists inserted rows, so it is empty for these field changes. If one batch operation is invalid, none apply. Use row IDs rather than list positions. See the operation reference.

Successful edits are saved. Errors go to stderr with a nonzero exit status. On a Mac, Edit ▸ Undo can revert agent edits in the open window. If a command’s outcome is uncertain, run get before retrying. Document creation and editing work on macOS and Linux; closed PNG/PDF export works on both platforms, and opening a window needs the Mac app.

Move data between documents

import writes a JSON file’s value into a document, changing only what differs. Rows are matched by $id, so rows and text that stay keep their identity, and fields the import leaves unchanged are not written at all; an open window keeps working on them. Pass --path to replace one part, such as '["rows"]':

bunx hitslop get Old.slop > data.json
bunx hitslop import New.slop data.json
bunx hitslop import New.slop rows.json --path '["rows"]'

Responses:

Command	Response
get Old.slop > data.json	JSON is written to data.json; nothing is printed in the terminal.
import New.slop data.json	{"ids":[]} when no rows are inserted; inserted rows appear in ids.
import New.slop rows.json --path '["rows"]'	The same {"ids":[...]} shape, with the IDs inserted by this edit.

Both documents must come from the same template, so the data fits its schema; a value that doesn’t fit is refused and nothing changes. For a document of another template, map the data to one batch of insert and set operations, giving each insert an id so a retried command is refused as a duplicate. Copy attachments with the commands below, then write their references. Edit ▸ Undo in the window reverts an import as one step.

Change theme colors

bunx hitslop theme get My.slop
bunx hitslop theme set My.slop --values '{"accent":"#7050ad"}'
bunx hitslop theme reset My.slop --token accent
bunx hitslop theme reset My.slop
bunx hitslop theme export My.slop --output Purple.json
bunx hitslop theme import Other.slop Purple.json

Example responses for the counter tutorial’s three-color palette:

Command	Response
theme get My.slop	{"defaults":{"accent":"#28634b","ink":"#382d24","surface":"#fff7e6"},"overrides":{},"effective":{"accent":"#28634b","ink":"#382d24","surface":"#fff7e6"}}
theme set My.slop …	{"defaults":{"accent":"#28634b","ink":"#382d24","surface":"#fff7e6"},"overrides":{"accent":"#7050ad"},"effective":{"accent":"#7050ad","ink":"#382d24","surface":"#fff7e6"}}
theme reset My.slop --token accent	The original theme get response above, with "overrides":{}.
theme reset My.slop	The same original palette, with all overrides cleared.
theme export My.slop --output Purple.json	/Users/you/Documents/Purple.json
theme import Other.slop Purple.json	The full defaults, overrides, and effective palette, like theme get.

These commands run in order, so this example exports the reset palette. Export before resetting if you want to keep the purple accent.

theme get reports the template’s colors, the document’s changes, and the effective palette. Set only colors the app declares, as lowercase #rrggbb or #rrggbbaa. Reset one color with --token, or omit it to reset them all. theme export prints the full palette as a theme file, or writes it with --output; theme import replaces the palette with a file made for the same template. The open window, its theme panel and subsequent captures use the changes. After an uncertain result, inspect theme get before retrying. See styling for declaring a theme.

Work with attachments

bunx hitslop attachments ref ./photo.png
# Store the printed reference where the app expects it, attaching the file in the same edit.
bunx hitslop apply My.slop --attach ./photo.png \
  --op '{"type":"set","path":["photo"],"value":{"id":"ATTACHMENT_ID","byteLength":48213,"name":"photo.png","mimeType":"image/png"}}'
bunx hitslop attachments list My.slop
bunx hitslop attachments export My.slop ATTACHMENT_ID \
  --output ./photo-copy.png

Example responses (ATTACHMENT_ID stands for the file’s actual content hash):

Command	Response
attachments ref ./photo.png	{"id":"ATTACHMENT_ID","byteLength":48213,"name":"photo.png","mimeType":"image/png"}
apply My.slop --attach ./photo.png …	{"ids":[]}
attachments list My.slop	[{"id":"ATTACHMENT_ID","byteLength":48213,"mimeType":"image/png"}]
attachments export My.slop ATTACHMENT_ID --output ./photo-copy.png	/Users/you/Documents/photo-copy.png

attachments ref prints a file’s reference (its ID, size, name and type) without reading the document. --attach on apply or batch saves the file in the same edit that stores the reference, so both succeed or neither does; repeat it for more files. Ask your agent to store the reference where the app expects it. A file nothing references any more is removed when the document closes, and a duplicate or shared copy carries only the files its document references. List shows saved attachment IDs and sizes.

Attachment export refuses existing output files and the document itself. After an uncertain edit, run get before another command.

Export PNG or PDF

bunx hitslop export My.slop --format png --output My.png
bunx hitslop export My.slop --format pdf --output My.pdf

Export saves your edits and prints the output path. Choose a new output path other than the .slop itself; an existing destination is refused. Both open and closed documents render saved data independently, using Export.svelte. Slops without this optional view refuse PNG/PDF export. PNG and selectable vector PDF use the Rust renderer. On macOS and Linux the CLI exports a closed document itself; an open one is exported by the Mac app that has it open. See icons and exports for capture layouts.

Successful exports print their resolved output paths, respectively:

/Users/you/Documents/My.png
/Users/you/Documents/My.pdf

Install agent skills

Agent skills link to your global CLI, so they update whenever you upgrade it. Install the CLI globally, then run the interactive installer to choose skills and agents:

bun install -g hitslop
slop skills install

Or, from a project directory, install for all detected agents at project scope:

slop skills install --all --scope project

After the skill and agent selections, install prints each installed skill and its agent directories. Example excerpt:

Installed "hitslop-authoring"

--all prints the same installation results without selection prompts. The preceding bun install -g hitslop prints Bun’s installation summary, including the slop executable.

Skills install for every project by default (global scope); add --scope project to link them into the current project only. Select skills once, then agents once. Installation only adds or repairs selected links; deselecting an item does not remove it. Bare skills is shorthand for skills install. Global links require a global install. Project links use the project’s pinned node_modules/hitslop, including when installed through bunx.

Upgrading the global CLI updates linked skills in place. If a link breaks or points somewhere else, repair it; add --scope project for project links:

slop skills repair

Example repair response when a link already points to the right place:

No repairs needed [hitslop-authoring] (global).

A repaired link instead reports Repaired "hitslop-authoring" for … (global), naming its agents.

To install skills for a new agent, run skills install again.

Remove installed links explicitly. Any copy of the CLI can do this:

slop skills uninstall --scope project
# Remove every installed hitSlop skill at this scope without prompts:
slop skills uninstall --all --scope project

Both uninstall forms report each removed skill and its agent directories. Example excerpt:

Removed "hitslop-authoring"

With nothing installed, the response is No installed skills (project). Use either interactive uninstall or --all; the second invocation will find no remaining links if the first removed everything.

The guides linked by init follow the project’s pinned node_modules/hitslop install. Upgrading that dependency updates the linked guides; upgrading the global CLI leaves them unchanged.

Upgrade the CLI

The Mac app and the hitslop package share a release version. Within a project, update its one pinned hitslop dependency and continue using its bun run scripts. A global CLI update does not change project dependencies. If the command protocol differs, the CLI names which installation needs updating before touching a document. Updating either installation preserves the app already saved inside every document.

Update the global CLI with bun install -g hitslop@VERSION, replacing VERSION with the matching released version. Installed agent skills point at the global CLI, so they update with it.

Interactive commands may show an update notice on stderr with that command, checked at most daily. Network failures do not fail your command. CI and piped commands skip these checks; set HITSLOP_NO_UPDATE_CHECK=1 to disable them in a terminal as well.

The CLI and native owner use the same generated socket contract. Socket requests carry the document path and the command protocol they are written in. Correlation IDs are not part of this contract; each request receives its reply on its own exchange.

apply submits one operation through the same batch path as batch. Both read modes use one owner snapshot: get prints its value, while get --snapshot includes the schema, the template’s colors (defaults), the version, the value and the effective colors (theme).