Agent workflows
Agent integration
Use the Parchment CLI as a stable interface for AI agents, coding assistants, and external automation.
The CLI is the preferred documented automation surface for most non-visual workflows. It gives agents stable command names, explicit auth requirements, predictable output modes, and a machine-readable manifest when needed.
The Purveyors web app and CLI both consume Parchment API contracts, keeping browser, terminal, and agent behavior aligned without runtime package coupling.
Recommended agent patterns
- For shell-based automation, authenticate once, then call purvey commands with JSON or CSV output that suits the surrounding workflow.
- For code-side integrations, use @purveyors/sdk against the stable Parchment API contracts instead of importing CLI runtime internals or screen-scraping help text.
- Use purvey context first when a model needs dense onboarding text. Use purvey manifest for the preferred machine-readable contract, or purvey context --json when an existing caller needs compatibility-parity output.
- Prefer purvey CLI commands for shell automation or @purveyors/sdk and the public Parchment API for code integrations; avoid deprecated /api/tools/* endpoints and private workspace route payloads.
How the web app and CLI stay aligned
- The app uses session-authenticated @purveyors/sdk clients for migrated chat operations. The CLI remains a separate Parchment API client and terminal surface; neither runtime imports the other.
- Coffee-app still has direct Supabase paths, including some inventory, roast, sales, tasting, catalog, market, and agent helpers. Those are tracked migration debt, not evidence that the CLI is the app integration layer.
- Read tools execute Parchment API operations directly. Write tools stay user-confirmed through proposal cards and constrained execution routes.
- This API-first architecture keeps terminal, browser, and agent workflows aligned on the same contracts without runtime package coupling.
Agent bootstrap sequence
purvey auth login --headless
purvey manifest --pretty
purvey catalog search --origin "Ethiopia" --json