CLI reference

Pugmark is primarily a CLI plus an IPC protocol for handler processes. On a fresh install with no flags, pugmark resolves its bucket from ~/.config/pugmark/context.yaml (auto-generated on first run, pointing at ~/.pugmark/buckets/default/), so the commands below all work without setup.

Managing sessions

pugmark start                              # create a new root session, switch context to it
pugmark sessions                           # list sessions in the current bucket
pugmark switch <id>                        # make <id> the current session
pugmark context                            # show current bucket, session, and snapshot

Sessions get a 128-bit time-embedded id by default. Give one a human-readable name with a ref:

pugmark link code-review                   # name the current session (stored under refs/)
pugmark refs                               # list named refs
pugmark switch code-review                 # named ref works wherever a session id works
pugmark unlink code-review                 # drop the name

Pushing and inspecting events

# push an inline event
pugmark push <<<'{"kind":"user_message","text":"hi"}'
pugmark push report.json data.csv          # push files; names become "report.json" / "data.csv"
pugmark push --name greeting hello.txt     # override name on a single-file push

# inspect what's in the current session
pugmark log                                # the session tree
pugmark log -A                             # tree + the objects on each snapshot
pugmark objects                            # objects at the current snapshot
pugmark cat <hash>                         # print one object's body
pugmark stat <hash>                        # metadata only
pugmark pull <hash> -o file.json           # save to disk

Forking

Branching a session at any snapshot is the unique pugmark move:

pugmark fork turn.json                     # fork current snapshot, seed the child with turn.json, switch to it
pugmark fork -s <id>:<version> turn.json   # fork from a specific snapshot
pugmark run --fork -- python agent.py      # branch with no seed object, then run a handler in the child
pugmark log -A                             # the resulting tree shows the branch

pugmark fork takes one or more seed files (one child per file); use pugmark run --fork to branch a bare child with no seed. The forked session inherits parent history; any new events you push only land in the fork.

Handlers

A handler is any process that reads pugmark events from stdin, fetches object data via the runtime’s HTTP endpoint, decides one next event, and writes it back to stdout. The protocol is documented in the Handler Protocol spec and is the contract behind the pre-1.0 stability promise.

pugmark run --start -- python agent.py     # create a new session, then loop until pause
pugmark run --once -- python agent.py      # single-shot against the current session
pugmark run -- python agent.py             # loop the current session until the handler pauses

Named handlers route by the session manifest’s handler field:

pugmark run --handler python='python agent.py' --handler bash='bash worker.sh' --start

You can write a handler in any language; the Python and Go SDKs cover the framing and object fetching for you.

Deployment

Terraform modules ship for AWS Lambda and GCP Cloud Run; each cloud function is triggered by object-creation notifications on the session bucket and invokes the configured handler. See terraform/resources/ and the lambda-deploy example for a working end-to-end deploy.

Storage layout

objects/sha256:<64-hex>                                                  # content-addressable objects
sessions/year=<yyyy>/month=<mm>/day=<dd>/hour=<hh>/<id>/
  manifest.json                                                          # session metadata + parent
  snapshots/<reverse-hex>.json                                           # versioned snapshots

Hive-style time-partitioned session keys keep prefix lists bounded and make the bucket queryable with table-aware tools (Athena, BigQuery, DuckDB). The full layout is defined in the Storage Layout spec.

Go library

Everything the CLI does is also available as a Go library (pugmark.StartSession, pugmark.StoreSnapshot, pugmark.ScanObjects, and so on) for tools that want to read and write sessions directly without spawning the CLI. See the godoc for the full surface.

Skills

Pugmark ships workflow-focused skills that teach coding agents (Claude Code, Cursor, Gemini) to drive the CLI and write handlers. Install them all via skills.sh:

npx skills add firetiger-oss/pugmark

Or, for an offline install pinned to the binary’s embedded version:

pugmark skills                        # browse the list
pugmark skills using-the-pugmark-cli  # render one on the terminal