SHVL CLI

Live Xero reports and reviewed drafts, from the terminal.

The SHVL CLI reads your credit-control workspace, pulls live Profit and Loss, Balance Sheet and Trial Balance reports from Xero, and prepares DRAFT invoices, quotes, supplier bills and purchase orders. Every draft needs an exact review and a typed confirmation. The CLI cannot send email, authorise a document, record a payment or activate a reminder schedule.

Start 30-day trial View on npm See pricing

What the CLI can and cannot do.

Area	Can	Cannot
Workspace	Show status, brief, receivables health, search and read cases.	Change case status, record payments or promises.
Synced Xero data	Search and read invoices and contacts from the last completed SHVL sync, with the sync timestamp.	Show customer email addresses or provider IDs.
Live Xero reports	Profit and Loss, Balance Sheet and Trial Balance for explicit dates, read-only, capped at 250 rows.	Change any Xero data.
Xero drafts	Prepare and create DRAFT invoices, quotes, supplier bills and purchase orders after an expiring review and typed confirmation.	Authorise, approve, send or pay anything in Xero.
Reminders	Nothing.	Activate, pause or send reminders. That stays in the workspace.

Commands.

Add --json to most read commands for script output.

Sign in and choose a workspace

shvl auth login
shvl workspace list
shvl workspace use WORKSPACE_ID
shvl workspace status
shvl brief
shvl receivables --json
shvl cases search "INV-2041"
shvl cases get case_123

Every protected request carries the selected workspace explicitly. With more than one workspace, SHVL stops until you choose one. The selected workspace and connected Xero organisation are shown before every write confirmation.

Review a CSV without an account

shvl csv analyse ./aged-debtors.csv --sender "Example Ltd" --bank-rate 4.25

Returns review-only draft content with indicative statutory interest and fixed compensation. Nothing is stored or sent.

Synced Xero reads

shvl xero invoices search Northwind --status overdue
shvl xero invoices get invoice_123
shvl xero contacts search Northwind
shvl xero contacts get customer_123

Live Xero financial reports

shvl xero reports profit-and-loss --from 2026-08-01 --to 2026-08-31
shvl xero reports balance-sheet --date 2026-08-31
shvl xero reports trial-balance --date 2026-08-31 --json

These call Xero live using separately granted read-only report access. The authorising Xero user must be able to open Reports.

Reviewed Xero drafts

shvl xero invoices candidates
shvl xero invoices options engagement_123
shvl xero invoices prepare engagement_123 ...
shvl xero invoices create REVIEW_ID

shvl xero quotes candidates | options | prepare | create
shvl xero bills documents | options | prepare | create
shvl xero purchases options | prepare | approve | list | create

Draft creation needs a separate Xero accounting.invoices grant, an exact set of provider choices, an expiring review and a typed confirmation phrase. The record lands in Xero as a DRAFT for a person to authorise there.

Access and secrets.

shvl auth login opens the normal SHVL sign-in and consent flow with OAuth PKCE and stores a refreshable session at ~/.config/shvl/cli.json with owner-only permissions. For automation, set SHVL_ACCESS_TOKEN in the process environment. Never put a token in a command argument, a repository or a shared prompt. shvl auth status checks the session; shvl auth logout removes it.

Environment: SHVL_API_URL (defaults to https://shvl.app), SHVL_ACCESS_TOKEN, SHVL_AUTH_FILE, SHVL_OAUTH_REDIRECT_URI (loopback only), SHVL_WORKSPACE_ID.

A provider-accepted reminder is not evidence of inbox delivery. Receivables health is not a cash-flow, profit or business-health report.

Practice workflow How data moves through SHVL Pricing

Included with Solo and Team.

Start a 30-day trial without card details, install the CLI, and run shvl brief against your own workspace.

Start 30-day trial Open product demo