--- name: pp-gusto description: "Prep a Gusto payroll from the terminal, including mileage reimbursements that Gusto's hosted connector cannot enter, and stop at review so a human submits. Trigger phrases: `run payroll prep in gusto`, `add mileage reimbursement to gusto payroll`, `check the gusto draft payroll`, `use gusto-pp-cli`, `run gusto`." author: "david" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - gusto-pp-cli install: - kind: go bins: [gusto-pp-cli] module: github.com/mvanhorn/printing-press-library/library/payments/gusto/cmd/gusto-pp-cli --- # Gusto — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `gusto-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install gusto --cli-only ``` 2. Verify: `gusto-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.10 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```bash go install github.com/mvanhorn/printing-press-library/library/payments/gusto/cmd/gusto-pp-cli@latest ``` If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. gusto-pp-cli drives Gusto's own web app with your signed-in session. It sets hours, adds reimbursements (payrolls mileage turns miles into a labeled line), calculates, and reads back gross, net and debit. payrolls verify proves the draft matches your timesheet before anyone clicks Submit. ## When to Use This CLI Use this CLI to prepare a Gusto payroll draft: set hours, add mileage or other one-time reimbursements, calculate, and read back totals for a human to submit. Requirements: macOS, the press-auth companion, and a signed-in app.gusto.com session. It drives Gusto's private web GraphQL API, which can change without notice. It writes only draft inputs (hours and one-time reimbursements) and never submits, approves or deletes a payroll; preview writes with --dry-run. Payroll data is always read live, not synced. ## Anti-triggers Do not use this CLI for: - Submitting or approving a payroll; a human does that in app.gusto.com - Hiring, onboarding, benefits, contractors or tax setup; use the Gusto web app or the official API - Adding a bonus; the bonus operation is not supported yet ## Unique Capabilities ### Payroll prep without the web UI - **`payrolls mileage`** — Add or correct the mileage reimbursement on the open draft payroll from miles and a per-mile rate; one mileage line per employee. _Reach for this whenever a timesheet lists trip miles; Gusto's hosted connector cannot put a reimbursement on a draft._ ```bash gusto-pp-cli payrolls mileage --period-end 2026-11-01 --employee 'Ava Example' --miles 5.2 --rate 0.60 --dry-run ``` - **`payrolls prep`** — Load a week's hours and mileage from a CSV onto the open draft, calculate it, and print the review totals, stopping before submit. _Use this for the weekly payroll ritual so a human only has to review and submit._ ```bash gusto-pp-cli payrolls prep --period-end 2026-11-01 --from week.csv --rate 0.60 --dry-run ``` ### Read-back you can trust - **`payrolls verify`** — Check the draft payroll against your timesheet CSV (hours, each reimbursement line, unexplained lines, duplicates) and exit 1 on any mismatch. _Run it before telling a human the payroll is ready; a non-zero exit means do not hand it off._ ```bash gusto-pp-cli payrolls verify --period-end 2026-11-01 --from week.csv --rate 0.60 --agent ``` - **`payrolls compare`** — Calculate the draft and show how its total debit and payable tax changed against the last processed payroll, alongside the draft's gross, reimbursements, taxes and net. _Use it to explain an unusual debit before the human submits._ ```bash gusto-pp-cli payrolls compare --period-end 2026-11-01 --agent ``` ## HTTP Transport This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls. ## Discovery Signals This CLI was generated with browser-observed traffic context. - Capture coverage: 14 API entries from 14 total network entries - Protocols: graphql (92% confidence) - Auth signals: chrome_mcp_session `--ca-cert`, `GUSTO_CA_CERT`, or `ca_cert` adds a PEM CA bundle to the system trust roots. `--tls-server-name`, `GUSTO_TLS_SERVER_NAME`, or `tls_server_name` is the name checked against the certificate. Precedence is flag, then environment, then the config file. A config file other users can change does not supply these settings. `doctor` reports the trust in use and names the setting that fixes a chain or hostname failure. ## Command Reference **session** — Your Gusto web session - `gusto-pp-cli session` — Show recent sign-in events for the signed-in Gusto user (confirms the session works) **payrolls** - `gusto-pp-cli payrolls mileage` — Add or correct the mileage reimbursement on the open draft payroll from miles and a per-mile rate; one mileage line per employee. - `gusto-pp-cli payrolls prep` — Load a week's hours and mileage from a CSV onto the open draft, calculate it, and print the review totals, stopping before submit. - `gusto-pp-cli payrolls verify` — Check the draft payroll against your timesheet CSV (hours, each reimbursement line, unexplained lines, duplicates) and exit 1 on any mismatch. - `gusto-pp-cli payrolls compare` — Calculate the draft and show how its total debit and payable tax changed against the last processed payroll, alongside the draft's gross, reimbursements, taxes and net. - `gusto-pp-cli payrolls due` — Show the next draft payroll: pay period, submit-by deadline and check date - `gusto-pp-cli payrolls history` — List processed payrolls with period, check date and total debit - `gusto-pp-cli payrolls show` — Show a draft payroll's inputs per employee: hours, bonus and reimbursement lines - `gusto-pp-cli payrolls hours set` — Set an employee's regular hours on the draft payroll - `gusto-pp-cli payrolls reimburse add` — Add a one-time reimbursement line; a line with the same description is replaced, not duplicated - `gusto-pp-cli payrolls reimburse list` — List reimbursement lines on a draft payroll - `gusto-pp-cli payrolls reimburse remove` — Remove reimbursement lines with a matching description from a draft payroll - `gusto-pp-cli payrolls review` — Calculate the draft payroll and show gross, reimbursements, taxes, net and total debit; never submits - `gusto-pp-cli payrolls net-pay-preview` — Preview each employee's gross and net pay on a draft payroll from its saved inputs **reimbursements** - `gusto-pp-cli reimbursements suggestions` — List the reimbursement descriptions Gusto suggests for this company ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash gusto-pp-cli which "" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. `--json` (and other machine formats) keep that exit-2 contract and write `{"matches":[]}` on stdout so agents can inspect the envelope without treating a miss as success. ## Recipes ### Mileage for one trip week ```bash gusto-pp-cli payrolls mileage --period-end 2026-11-01 --employee 'Ava Example' --miles 7.8 --rate 0.60 ``` Writes one reimbursement line, Mileage 7.8 mi x $0.60, onto the draft. ### Weekly prep from a CSV ```bash gusto-pp-cli payrolls prep --period-end 2026-11-01 --from week.csv --rate 0.60 ``` Sets hours and mileage for each employee, calculates, and prints the review totals. ### Gate the handoff ```bash gusto-pp-cli payrolls verify --period-end 2026-11-01 --from week.csv --rate 0.60 --agent --select ok,mismatches ``` Returns only the pass flag and the mismatch list so an agent can decide whether to hand off. ### Read only the totals that matter ```bash gusto-pp-cli payrolls review --period-end 2026-11-01 --agent --select review.gross,review.net_pay,review.total_debit ``` Calculates the draft and returns just gross, net and total debit for the human who submits. ## Auth Setup This CLI uses your Gusto web session, not an API key, and works on macOS only. Step 1: install press-auth (go install github.com/mvanhorn/cli-printing-press/v4/cmd/press-auth@latest) and run press-auth login app.gusto.com --login-url https://app.gusto.com/login --complete-selector 'a[href="/pay"]'; sign in in the window it opens and choose Always Allow on the Keychain prompt. Step 2: run gusto-pp-cli auth login --chrome, which imports that session (it can also fall back to pycookiecheat, cookies or cookie-scoop-cli). Check it with gusto-pp-cli doctor. Sessions expire; repeat both steps when requests land on the login page. Run `gusto-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. Global format flags share one contract on promoted, novel, sync, and `--deliver` paths: - `--json` — one JSON document on stdout (sync progress events go to stderr) - `--compact` — keep identity/status/timestamp fields; does not change the document vs stream shape - `--csv` / `--plain` — tabular rows (collection envelopes unwrap to the row array). `--csv` prefixes `'` on a cell or header key that starts with `=`, `+`, `-`, `@`, tab, CR, or LF (fullwidth `＝＋－＠` too) so a spreadsheet does not run it as a formula; a plain signed number such as `-5` or `+2.5e3` is unchanged. - `--quiet` — one identity value per row, no envelope - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash gusto-pp-cli payrolls review --period-end 2026-11-01 --agent --select review.gross,review.net_pay,review.total_debit ``` - **Previewable** — `--dry-run` shows the request without sending - **Live payroll data** — payroll commands always read Gusto live; sync and search cover only the `session` resource - **Non-interactive** — never prompts, every input is a flag - **Draft writes only** — writes only to draft payrolls (hours and one-time reimbursements). It never submits or approves a payroll and cannot add bonuses. Preview any write with `--dry-run`; writes apply immediately without `--yes` ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home ` for one invocation, or set `GUSTO_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `GUSTO_CONFIG_DIR`, `GUSTO_DATA_DIR`, `GUSTO_STATE_DIR`, `GUSTO_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `GUSTO_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults. - `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, cookies, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files. - Stored secrets live in `credentials.toml` under the data dir. Existing legacy `config.toml` secrets are read for compatibility and leave `config.toml` on the first auth write. - Run `gusto-pp-cli doctor --fail-on warn` to surface path and credential-location warnings. `agent-context` exposes a schema v4 `paths` block for agents that need the resolved dirs. - For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags: ```json { "mcpServers": { "gusto": { "command": "gusto-pp-mcp", "env": { "GUSTO_HOME": "/srv/gusto" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `GUSTO_HOME` or per-kind vars as durable fleet levers, and use `--home` only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing `GUSTO_HOME`, or `doctor` will not find credentials left under the former root. Local data is unencrypted and relies on OS account permissions plus disk encryption. Reads in the default `--data-source auto` mode are written to the SQLite store; GET responses are cached for five minutes under the cache dir. `local-data purge` previews what it would erase (store files, response cache, learn journal) and deletes only with `--yes`; it is not exposed over MCP. `GUSTO_NO_LOCAL_DATA=1` disables the response cache and store writes, turns `auto` reads into live reads, and blocks `sync` and `workflow archive`; `--data-source local` still reads an existing store, and `GUSTO_DATA_SOURCE` sets the `--data-source` default. ## Automatic learning This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a `flag_alias` candidate, and a `teach` on a query family without a playbook auto-synthesizes a `playbook_candidate` from the session's journal. Your job is judgment only: `recall` first, act on surfaced candidates, `teach` the final answer, `playbook amend` when you observe a correction. You never record failures by hand. ### Step 1: `recall` before any discovery Before list/search/drill commands on a new user question, pass the question as an argv or MCP tool argument to `recall --agent`. Do not interpolate user-controlled text into a shell command line. Quoted `recall ""` breaks on an apostrophe, which is ordinary English. A quoted heredoc breaks when a body line equals the delimiter, and that delimiter is published in these docs. Write the question with a non-shell file-writing tool, then read it back as data: ```bash # Write the question verbatim with your file-writing tool (no shell involved). # Command substitution on a file only ever yields data — the shell never # parses the file's bytes as syntax. QUERY=$(cat /path/to/question.txt) gusto-pp-cli recall "$QUERY" --agent ``` Prefer MCP: pass the question as the tool's query argument. `"$QUERY"` after a file read is argv-safe; putting the question itself in the command text is not. The response envelope: ```json { "query": "...", "normalized": "", "query_entities": ["..."], "found": true | false, "match_score": 0.0, "results": [ { "resource_id": "...", "resource_type": "...", "venue": "...", "confidence": 2, "entity_match": "exact|partial|unknown", "source": "taught|preseed|pattern", "warnings": ["..."] } ], "mismatches": [ /* only when --debug-mismatches */ ], "warnings": [ /* top-level */ ], "candidates": [ { "id": 12, "class": "flag_alias | playbook_candidate", "summary": "...", "sightings": 3, "last_seen": "...", "rationale": "...", "next_action": ["", "gusto-pp-cli learnings confirm 12"] } ], "playbook": { "query_family": "...", "playbook": { "steps": [ { "cmd": "", "purpose": "..." } ], "entity_slots": ["$ENTITY"], "expected_tool_calls": 3 }, "slots_resolved": { "$ENTITY": { "token": "", "canonical": "" } }, "notes": "" }, "notes": "" } ``` Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and `learnings list` and `learnings candidates` are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught. ### Step 2: decision tree Read `candidates`, `playbook`, `notes`, `results[0]`, and warnings in that order: ``` if Candidates present (warnings include "candidates_present"): -> candidates are try-then-confirm, never facts. Follow each candidate's two-step next_action verbatim: run the trial command first, then run `learnings confirm ` only after the trial verified the behavior. Reject a wrong candidate with `learnings reject `. -> NEVER re-teach something recall surfaced as a candidate; confirm or reject that candidate instead of teaching a duplicate. -> candidates ride alongside playbooks and resource hits, not instead of them; continue with the branches below after acting on them. if Playbook present: -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose) -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries for the entity slot tokens. If a step's slot is unresolved, fall back to discovery for that step only. -> the Playbook's expected_tool_calls is a budget; if you find yourself running materially more, record the divergence via `gusto-pp-cli playbook amend` at end-of-session. elif Notes present (no Playbook): -> read Notes verbatim before any discovery step; they carry known gotchas for this query family even when no structured choreography exists yet. elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2: -> skip discovery; fetch live data for Results[*].ResourceID in parallel elif Found AND Results[0].EntityMatch == "partial": -> candidate hint, NOT a hit; read the resource title to validate before trusting elif (any row in Mismatches[] when --debug-mismatches was passed): -> treat as cold start; the stored learning is for a different entity (different canonical resolved from query_entities) else: // Found == false, no playbook, no notes -> cold start; run discovery normally; teach the answer afterward (Step 4). If the family has no playbook yet, that teach auto-synthesizes a playbook candidate from this session's journal - you do not need to record one by hand. ``` Playbook and Notes are orthogonal to the per-resource path. A recall response can carry both a Playbook AND a `Results[]` hit - use both: the Playbook tells you which choreography to run; the resource hits short-circuit specific steps