SHVL CLI

Check overdue invoices from your terminal.

See overdue invoices, find a customer and check their reminder history. Workspace owners can also search synced Xero invoices and contacts or request live financial reports. Reviewed drafts require a separately enrolled write connection. Sending a payment-query request or creating a draft requires review and typed confirmation.

What the CLI can and cannot do.

AreaCanCannot
WorkspaceRead cases, timelines and a practice-wide attention queue.Record payments, resume chasing or change a reminder schedule.
Accounts PrepCreate draft checklists, read submitted handovers and confirm acceptance or return decisions.Send the follow-up, read supporting file contents or prepare statutory accounts.
Payment blockersCheck payment details and promised dates, then separately approve a blocker request when needed.Resume the paused case, retry an uncertain send or claim provider acceptance as delivery.
Synced Xero dataSearch and read invoices and contacts from the last completed SHVL sync, with the sync timestamp.Show customer email addresses or provider IDs.
Live Xero reportsProfit and Loss, Balance Sheet and Trial Balance for explicit dates, read-only, capped at 250 rows.Change any Xero data.
Xero draftsPrepare 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 schedulesRead 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, check payment details, 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

Supplier bills and credit notes

In CLI 0.7.4, workspace owners with an existing expanded SHVL connection and an active trial or subscription can review supplier payment methods and current Xero credit suggestions. Credit review requires a connected Xero organisation.

shvl xero bills review --json
shvl xero credits review --json

Unknown payment methods stay unknown. A team review does not verify a bank mandate. Credit suggestions match contact, currency and ledger side and show remainders. Nothing is allocated, paid or approved by these reads. Review and carry out allocations in Xero.

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.

Connection access.

New sign-ins have read-only credit-control and Xero access. Select a business first. Its owner can search synced Xero invoices and contacts. Live Profit and Loss, Balance Sheet and Trial Balance reports need a connected Xero organisation with the relevant report permission.

To add report permission, open Credit control, select Credit control, then Connections and team and Accounting. Choose Connect Xero permissions or Add Xero report access, as shown for your connection.

Request expanded access. Ledger reviews and Xero draft creation require an enrolled connection. Expanded connections include reviewed write tools too; each write still needs approval of the exact action. Include your workspace name and the read or draft actions you need. Do not send passwords or tokens.

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.

Included with SHVL.

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

Start 30-day trialTry the demo