CLI Reference

PAS-Agent is a single binary, pas-agent. Every command exceptinit finds the session by walking up from the current directory.

pas-agent init

Create a new session.

pas-agent init [OPTIONS]

Options:
  -n, --name <NAME>   Project name (defaults to the project directory name)
  -t, --task <TASK>   Task description (prompted for if omitted)

Creates .pas-agent/session.json at the git repository root, or in the current directory outside git, and records the current git state.

pas-agent update

Change the task state. List flags can be repeated; each value is one item.

pas-agent update [OPTIONS]

Options:
  --task <TASK>          Set task description
  --objective <OBJ>      Set objective
  --next <ACTION>        Set next action
  --clear-next           Clear the next action
  --completed <ITEM>     Add a completed item
  --remaining <ITEM>     Add a remaining item
  --decision <ITEM>      Add a decision
  --blocker <ITEM>       Add a blocker
  --constraint <ITEM>    Add a constraint
  --discovery <ITEM>     Add a discovery
  --done <N>             Move remaining item #N to completed
  --resolve <N>          Remove resolved blocker #N

N is the number shown by pas-agent status. Numbered operations run before items are added, so the numbers match what you saw. If any number is invalid, nothing is changed.

pas-agent remove

Remove items from a list by number.

pas-agent remove <LIST> <N>...

Lists: completed, remaining, decisions, blockers, constraints, discoveries

pas-agent checkpoint

Save a checkpoint of the current session state.

pas-agent checkpoint [MESSAGE...]

Records the git state, the files with uncommitted changes, and a snapshot of the task state. You're prompted for a message if you don't give one.

pas-agent status

Show the session: task, numbered lists, live git state, and the latest checkpoint.

pas-agent status

If files or the git commit changed after the latest checkpoint, it also prints a warning and lists the affected paths. See stale checkpoints.

pas-agent list

List all checkpoints with timestamp, message, file count, and commit.

pas-agent list

pas-agent export

Write session context into the file a target agent reads at startup.

pas-agent export --to <AGENT> [OPTIONS]

Options:
  -t, --to <AGENT>      claude-code, codex, opencode, kiro-cli, antigravity, gemini-cli, cursor
  -o, --output <PATH>   Output file (defaults to CLAUDE.md, AGENTS.md or GEMINI.md in the project root)
      --force           Replace the whole file instead of only the PAS-Agent block

If the working tree changed after the latest checkpoint, export prints the same warning as status on stderr, still writes the file, and adds aChanged Since Last Checkpoint section to it. If the output file is a symlink, the file it points to is updated and the link is kept. For Antigravity, which ignores anything past 12,000 characters of a rules file, a file longer than that prints a warning on stderr. Unknown targets are rejected. See Portable Statefor how the block is written.

Examples

# Initialize with task
pas-agent init --task "Implement user authentication"

# Record progress
pas-agent update --completed "Login endpoint" --completed "Password hashing" \
                 --remaining "Token refresh" --next "Implement token refresh"

# Finish remaining item #1
pas-agent update --done 1

# Save checkpoint
pas-agent checkpoint "Login complete"

# Export for Codex
pas-agent export --to codex