SHVL CLI

Run reviewed credit control and Xero work from the terminal.

The SHVL CLI reads your credit-control workspace, sends an explicitly approved request when an invoice is blocked by a missing PO or evidence, pulls live Xero reports, and prepares DRAFT invoices, quotes, supplier bills and purchase orders. Every external write shows the exact details and requires a typed confirmation.

Start 30-day trial View on npm See pricing

What the CLI can and cannot do.

Area	Can	Cannot
Workspace	Read cases, timelines and a practice-wide attention queue.	Record payments, resume chasing or change a reminder schedule.
Accounts Prep	Create draft checklists, read submitted handovers and confirm acceptance or return decisions.	Send the follow-up, read supporting file contents or prepare statutory accounts.
Payment blockers	Review readiness checks and payment promises, then separately approve a blocker request when needed.	Resume the paused case, retry an uncertain send or claim provider acceptance as delivery.
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.
Reminder schedules	Read the case and its latest communication status.	Activate or change a schedule. 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

Case and handover commands carry the selected workspace explicitly. With more than one workspace, choose one before using those commands. The practice attention command reads across your entitled workspaces without changing that selection.

Review client work across the practice

shvl practice attention --json
shvl cases timeline CASE_ID --json
shvl cases add-activity CASE_ID --file activity.json --request-id UUID_V4
shvl blockers get CASE_ID --json
shvl blockers update CASE_ID --file readiness.json
shvl handovers create --file checklist.json --request-id UUID_V4

Read the timeline, add a dated note, call or manually supplied email, review payment readiness, or create a draft Accounts Prep request. Writes show the selected workspace and exact changes before typed confirmation. They do not send, resume chasing or share a client link. Keep the same request ID when retrying activity or checklist creation. Manual activity is labelled separately from verified events. The npm reference includes the JSON file formats.

Reviewed payment-blocker request

shvl blockers options case_123
shvl blockers send case_123 \
  --to accounts@example.com \
  --subject 'Purchase order needed for INV-1042' \
  --message-file ./request.txt \
  --follow-up 2026-09-17 \
  --invoice invoice_123 \
  --document document_request_123

The send command displays the workspace, mailbox, recipient, wording, invoice IDs, evidence and follow-up date before asking for a unique confirmation phrase. SHVL then rechecks the invoice and blocker. The case stays paused, and an uncertain provider result is not retried automatically.

Review client handovers

shvl handovers list
shvl handovers get PACK_ID
shvl handovers review PACK_ID --decisions-file review.json

Review supporting files in the workspace first. Saving decisions requires the workspace owner, active access and the exact confirmation phrase shown by the CLI. Identical retries reuse the saved review and follow-up.

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