CLI Commands

Global flags

Flag	Type	Default	Description
`--log-level`	string	From config	Override log level (`debug`, `info`, `warn`, `error`)

`partio enable`

Enable partio in the current Git repository.

partio enable [--absolute-path]

Flag	Type	Default	Description
`--absolute-path`	bool	`false`	Install hooks using the absolute path to the partio binary

What it does:

Verifies you’re inside a Git repository
Ensures the .partio/ config directory exists
Writes a default settings.json (existing config is preserved)
Adds .partio/settings.local.json to .gitignore
Installs Git hooks (pre-commit, post-commit, pre-push)
Ensures the partio/checkpoints/v1 orphan branch exists

partio enable is idempotent — safe to re-run at any time to repair hooks or restore settings. Re-running preserves your existing configuration (it only flips enabled back to true if partio was disabled) and never overwrites custom values. --absolute-path: By default, hooks invoke partio by name and rely on PATH resolution at hook execution time. Use --absolute-path if partio is not on PATH in your hook execution environment — for example, when using nix, asdf, mise, or system-level git hooks.

partio enable --absolute-path

This embeds the resolved absolute path of the partio binary into the installed hook scripts. Output:

partio enabled successfully!
  - Ensured .partio/ config directory exists
  - Installed git hooks (pre-commit, post-commit, pre-push)
  - Ready to capture AI sessions on commit

External hook managers: If partio detects another Git hook manager — Husky, Lefthook, or Overcommit — partio enable prints a warning with integration instructions and continues (it does not abort). partio’s hooks must be invoked from within your hook manager’s configuration via partio _hook <hook-name> so both run:

Warning: Husky detected.
  Partio's hooks must be called from within your hook manager's configuration.
  Add partio hook calls to your Husky hook scripts. For example, in .husky/pre-commit add:
    partio _hook pre-commit
  and in .husky/post-commit add:
    partio _hook post-commit

`partio disable`

Disable partio in the current repository.

partio disable [--remove-data]

Flag	Type	Default	Description
`--remove-data`	bool	`false`	Also delete the `.partio/` directory and all config

What it does:

Removes partio-managed hooks from .git/hooks/
Restores any backed-up original hooks
If --remove-data: deletes .partio/ directory

Output (default):

partio disabled.
  - Removed git hooks (originals restored from backup if present)
  - Checkpoint data and config preserved (use --remove-data to delete)

`partio status`

Show partio status for the current repository. Also runs automatic stale session cleanup before displaying results.

partio status

Output (enabled):

Repository: /path/to/your-project
Branch:     main
Status:     enabled
Strategy:   manual-commit
Linking:    ask
Agent:      claude-code
Hooks:      installed
Checkpoints: branch exists

Output (not enabled):

Repository: /path/to/your-project
Branch:     main
Status:     not enabled (run 'partio enable' to set up)

`partio rewind`

List or restore checkpoints.

partio rewind --list [--branch <name>]
partio rewind --to <checkpoint-id>

Flag	Type	Default	Description
`--list`	bool	`false`	List all stored checkpoints
`--to`	string	`""`	Restore to a specific checkpoint ID (12 hex characters)
`--branch`	string	`""`	Filter checkpoints by branch name (useful for squash-merged branches)

--list output:

Checkpoints:

  a3f8c2d14e9b  branch=main           agent=87%   created=2026-02-17T14:30:00Z
  bb12340092ac  branch=feature/auth    agent=100%  created=2026-02-16T09:15:22Z

--list --branch output: Filters the list to checkpoints whose branch name exactly matches the given value:

partio rewind --list --branch feature/auth

Checkpoints:

  bb12340092ac  branch=feature/auth    agent=100%  created=2026-02-16T09:15:22Z

This is the recommended way to find sessions for a branch that was squash-merged into main. --to output:

Rewinding to checkpoint a3f8c2d14e9b
  Commit: 4f9a2c...
  Branch: main
  Context:
  <session context summary>
  Created branch: partio/rewind/a3f8c2d14e9b

This creates a new branch named partio/rewind/<id> checked out at the checkpoint’s commit. If the original commit is no longer reachable (e.g. the branch was squash-merged and the original commits were garbage-collected), partio emits a warning and exits without creating a rewind branch — the session context is still shown:

Warning: original commit a3f8c2d is no longer reachable (likely squash-merged or gc'd); session context is still available but branch checkout is skipped.

`partio resume`

Resume a session from a checkpoint. Reads checkpoint data from the orphan branch and launches a new Claude Code session with the previous context.

partio resume <checkpoint-id>
partio resume --branch-name <branch>

Flag	Type	Default	Description
`--print`	bool	`false`	Print the composed context prompt to stdout
`--copy`	bool	`false`	Copy the context prompt to clipboard
`--branch`	bool	`false`	Create a branch at the checkpoint’s commit before launching
`--branch-name`	string	`""`	Resume the most recent session from the named branch (recommended for squash-merged work)

Default behavior: Writes a context file to a temporary directory and launches Claude Code with instructions to read it and continue the previous work. If Claude Code is not found in PATH, the context is printed to stdout instead. With --branch-name: Finds all checkpoints for the named branch, selects the most recent one by creation time, and resumes it. This is the recommended approach for sessions whose branch was squash-merged into main:

partio resume --branch-name feature/my-branch

Either a positional <checkpoint-id> or --branch-name is required; invoking resume with neither exits non-zero with a usage error. With --branch: Creates a new branch named partio/resume/<id> checked out at the checkpoint’s commit before launching.

Created branch: partio/resume/a3f8c2d14e9b
Context written to /tmp/partio-resume-a3f8c2d14e9b.md
Launching Claude Code...

With --print:

partio resume a3f8c2d14e9b --print

Prints the composed context prompt (including the original request, plan, diff, and session metadata) to stdout without launching Claude Code. With --copy: Copies the context prompt to the system clipboard (macOS and Linux).

`partio doctor`

Check partio installation health.

partio doctor

Checks performed:

.partio/ directory exists
pre-commit hook installed, readable, and managed by partio
post-commit hook installed, readable, and managed by partio
pre-push hook installed, readable, and managed by partio
partio/checkpoints/v1 branch exists
partio binary found in PATH

Output (healthy):

[OK]   .partio/ directory exists
[OK]   pre-commit hook installed
[OK]   post-commit hook installed
[OK]   pre-push hook installed
[OK]   checkpoint branch exists
[OK]   partio binary found (you're running it!)

All checks passed!

Output (issues found):

[WARN] .partio/ directory missing - run 'partio enable'
[WARN] pre-commit hook missing
[OK]   post-commit hook installed
[WARN] post-commit hook exists but not managed by partio
[WARN] post-commit hook unreadable: permission denied
[WARN] checkpoint branch missing
[OK]   partio binary found (you're running it!)

5 issue(s) found. Run 'partio enable' to fix.

`partio prune`

Delete checkpoints older than a retention window from the partio/checkpoints/v1 branch.

partio prune [--older-than 90d] [--dry-run]

Flag	Type	Default	Description
`--older-than`	string	`"90d"`	Retention window; removes checkpoints older than this (e.g. `30d`, `90d`, `365d`)
`--dry-run`	bool	`false`	Preview what would be deleted without making any changes

The checkpoint linked to the current HEAD is never removed. partio rebuilds the orphan branch’s tree with git plumbing to drop the pruned entries. Dry-run output:

Dry run — no changes made.

  Would remove a3f8c2d14e9b (branch=feature/auth, created=2026-01-04T09:15:22Z)
  Would remove bb12340092ac (branch=main, created=2026-01-02T14:30:00Z)

2 checkpoint(s) would be removed, 5 kept.

Real run output:

  Removed a3f8c2d14e9b (branch=feature/auth, created=2026-01-04T09:15:22Z)

1 checkpoint(s) removed, 6 kept.

If nothing qualifies:

No checkpoints to prune.

`partio reset`

Reset the checkpoint branch. This deletes all stored checkpoint data and recreates the branch.

partio reset

Output:

Checkpoint branch reset successfully.

This permanently deletes all checkpoint data. This cannot be undone.

`partio clean`

Remove orphaned checkpoint data.

partio clean

Scans the checkpoint branch for data that no longer corresponds to any commit. Output:

Checkpoint data present on partio/checkpoints/v1 branch.
To fully reset, run: partio reset

`partio cleanup`

Manually clean up stale session files left behind by crashed or improperly terminated agent processes.

partio cleanup

A session is considered stale when:

It is in ACTIVE or IDLE state, and
Its state file has not been updated within the configured threshold (default: 10 minutes), and
If a process ID is recorded, the agent process is no longer alive.

Output (stale session found):

Cleaned up stale session: <session-id> (agent=claude-code)

Output (no stale sessions):

No stale sessions found.

partio status also runs stale cleanup automatically before displaying results, so manual invocation is usually not necessary. Not to be confused with partio clean, which removes orphaned checkpoint data.

`partio version`

Print the partio version.

partio version

Output:

partio v0.1.0

Getting Started

CLI Reference

App

Extension

Integrations

Commands

CLI Commands

Global flags

`partio enable`

`partio disable`

`partio status`

`partio rewind`

`partio resume`

`partio doctor`

`partio prune`

`partio reset`

`partio clean`

`partio cleanup`

`partio version`

​CLI Commands

​Global flags

​partio enable

​partio disable

​partio status

​partio rewind

​partio resume

​partio doctor

​partio prune

​partio reset

​partio clean

​partio cleanup

​partio version

CLI Commands

Global flags

`partio enable`

`partio disable`

`partio status`

`partio rewind`

`partio resume`

`partio doctor`

`partio prune`

`partio reset`

`partio clean`

`partio cleanup`

`partio version`