Pacto CLI Getting Started

The default loop is simple: initialize a workspace, create a plan slice, verify the current state, execute the work, and move the slice forward explicitly.

1. Initialize the workspace

Pacto creates a plans workspace under .pacto/plans.

pacto init

.pacto/
├── config.yaml
└── plans/
    ├── current/
    ├── to-implement/
    ├── done/
    ├── outdated/
    ├── README.md
    └── PACTO.md

Optional agent-friendly setup:

pacto init --no-interactive --tools codex,cursor --yes

2. Create a plan slice

pacto new to-implement improve-auth-flow

The slice starts with a README, spec, design, and tasks document under the chosen state.

3. Verify state and evidence

pacto status
pacto status --format json --verify --fail-on partial

This is the command that makes Pacto different: it checks plan claims against repository evidence instead of relying on narrative status updates.

4. Record execution progress

pacto exec current improve-auth-flow --note "Started implementation"
pacto exec current improve-auth-flow --step 1.1 --evidence src/auth/flow.go

5. Move the slice forward explicitly

pacto move to-implement improve-auth-flow current
pacto move current improve-auth-flow done --reason "All tasks complete and verified"

6. Explore ideas before they are formal work

pacto explore auth-refresh --title "Auth refresh ideas"
pacto explore auth-refresh --note "Compare token vs session model"
pacto explore --list

Root discovery

Commands such as pacto status and pacto new auto-discover the plans root from the current directory and its parents. Use explicit roots when you need to target a specific repository.

pacto status --root . --repo-root .
pacto new to-implement my-plan --root .