# NQD CLI The NQD CLI is a thin, scriptable client for the NQD resource API. It uses the same published REST contract as the dashboard. ## Landing page Landing page: https://cli.nqd.app/ English: https://cli.nqd.app/?lang=en Arabic: https://cli.nqd.app/?lang=ar Machine-readable help: https://cli.nqd.app/llms.txt Full machine-readable help: https://cli.nqd.app/llms-full.txt README endpoint: https://cli.nqd.app/README.md Use `?platform=macos`, `?platform=linux`, or `?platform=windows` to choose an install target. The landing page lists six native archives and their `SHA256SUMS` file. ## Install macOS or Linux: `curl -fsSL https://cli.nqd.app/install.sh | sh` Windows PowerShell: `irm https://cli.nqd.app/install.ps1 | iex` The Unix installer uses `$NQD_INSTALL_DIR` or `$HOME/.local/bin`. It persists PATH changes for zsh and bash, and prints a PATH command for other shells. The PowerShell installer uses `$NQD_INSTALL_DIR` or `$env:LOCALAPPDATA\NQD`, and updates the user and current-process PATH values. Set `NQD_CLI_VERSION` to choose a release or `NQD_CLI_RELEASE_BASE` to use another HTTPS release host. ## Authenticate Set `NQD_API_ORIGIN` for another API deployment, then run `nqd login` for OAuth PKCE. CI can set `NQD_API_KEY`; keys are read from the environment and never written to disk. ## Sources and cash transactions NQD records five kinds of sources. A source describes what creates or holds value. A Transaction is a separate cash event against a source, so a source can be unpaid or partially paid. - **Invoice:** Incoming service work for a Client or Project, described by Entries. A Transaction records payment from the client. - **Income:** Other incoming cash, such as capital, an inheritance, or a product receipt. It can link to the Client that paid for a product, but it does not require a service-work relationship. - **Expense:** Outgoing service cost paid to the selected Vendor. The Vendor can be an individual or a company. - **Payout:** Outgoing service payment to the selected individual Contact. It can link to a Client, Project, or customer Invoice. - **Asset:** A non-cash wealth holding. Its acquisition can have a separate cash Transaction. If the same person is both a Vendor and a Contact, the selected payee role decides the source type: Vendor means Expense; individual Contact means Payout. If no Client is selected, the source is Workspace-owned. NQD does not create a placeholder Client for the Workspace. An **Entry** is a reusable priced unit, such as a service, product, or subscription plan. Its quantity and net unit price are saved on the source. Catalog edits do not rewrite saved applied Entries. A **Modifier** changes an Entry or the source total. Use the supported fixed or percentage increase/decrease operation for the source. Applied Modifier values and targets are saved with the source. ## Native commands Use a resource name as the command. The CLI supplies the normal list defaults, including the selected workspace and the API default page size. ```sh nqd invoices nqd expenses nqd clients nqd reports income-statement ``` Use `--limit`, `--search`, `--order`, `--cursor`, and resource-specific filter flags when you need a different list. ```sh nqd invoices --limit 50 --search Acme --order createdAt.desc nqd expenses --filter-vendor-id eq.vendor_01J... ``` Use `create`, `update`, and `delete` for resource changes. Pass an ID as a positional argument. The short form retrieves a record, and the explicit `get` form is equivalent. ```sh nqd clients create --name Acme --type company nqd clients get client_01J... nqd clients client_01J... nqd clients update client_01J... --name "Acme Ltd" --type company nqd clients delete client_01J... ``` Nested resources follow the same shape. The parent ID comes before the child resource. ```sh nqd invoices invoice_01J... transactions nqd invoices invoice_01J... transactions create --id transaction_01J... --signed-amount 250.00 --currency-id currency_01J... nqd invoices templates ``` ### Manage party contacts Clients and vendors expose their contacts as child resources. Listing the child resource needs no operation name. Add or remove a contact with its positional ID. ```sh nqd clients CLIENT_ID contacts nqd clients CLIENT_ID contacts add CONTACT_ID nqd clients CLIENT_ID contacts remove CONTACT_ID nqd vendors VENDOR_ID contacts nqd vendors VENDOR_ID contacts add CONTACT_ID nqd vendors VENDOR_ID contacts remove CONTACT_ID ``` ### Manage applied entries and modifiers Invoices, expenses, income, assets, payouts, and their recurring templates use the same child workflow. The source ID comes first, followed by `entries` or `modifiers`. ```sh nqd invoices INVOICE_ID entries nqd invoices INVOICE_ID entries add CATALOG_ENTRY_ID --if-match UPDATED_AT --name Hosting --quantity 2 --price-per-unit 100 nqd invoices INVOICE_ID entries update APPLIED_ENTRY_ID --if-match UPDATED_AT --quantity 3 nqd invoices INVOICE_ID entries remove APPLIED_ENTRY_ID --if-match UPDATED_AT nqd invoices INVOICE_ID entries reorder APPLIED_ENTRY_ID OTHER_APPLIED_ENTRY_ID --if-match UPDATED_AT nqd invoices INVOICE_ID modifiers nqd invoices INVOICE_ID modifiers add CATALOG_MODIFIER_ID --if-match UPDATED_AT --name ServiceFee --kind percentage --stage price --effect increase --value 15 nqd invoices INVOICE_ID modifiers update APPLIED_MODIFIER_ID --if-match UPDATED_AT --value 20 nqd invoices INVOICE_ID modifiers remove APPLIED_MODIFIER_ID --if-match UPDATED_AT nqd invoices INVOICE_ID modifiers reorder APPLIED_MODIFIER_ID OTHER_APPLIED_MODIFIER_ID --if-match UPDATED_AT ``` Use the same child paths with `expenses`, `income`, `assets`, `payouts`, `invoices templates`, `expenses templates`, and `payouts templates`. Replace the source ID with the record or recurring-template ID. The positional catalog ID is optional. When supplied, it links the new applied record to a catalog definition without making the catalog ID the applied record ID. For recurring templates, place the template collection and template ID before the child resource, for example `nqd invoices templates TEMPLATE_ID entries` or `nqd expenses templates TEMPLATE_ID modifiers`. `APPLIED_ENTRY_ID` and `APPLIED_MODIFIER_ID` identify saved facts on the source. Catalog changes do not rewrite them. Pass the source response's current `updatedAt` value to `--if-match`; stale mutations fail instead of overwriting a newer edit. Entry prices are authored net prices and exclude VAT. Applied modifier `value` uses percentage points: `15` means 15%, while fixed modifiers use the amount in the source currency. Generic catalog modifiers use the stage allowed for that source, such as `price` in the example. For invoices, tax-stage applications use the configured workspace tax modifier; use its catalog ID (for example `TAX_MODIFIER_ID`). Other sources validate modifier stages according to their source rules. Saved payments remain recorded and are not replaced by child edits. Reports use readable names. The command maps to the corresponding report endpoint and accepts the date and filter options published for that report. ```sh nqd reports income-statement --start 2026-01-01 --end 2026-12-31 nqd reports balance-sheet --start 2026-01-01 --end 2026-12-31 nqd reports cash-flow --start 2026-01-01 --end 2026-12-31 ``` Use `nqd help ` or `nqd help ` to see the operations and fields that exist for that resource. You can also append `help` to a command, such as `nqd invoices create help`. The CLI generates these pages from the published API contract, so a resource does not advertise actions that the API does not provide. Assets have no delete command, and transactions have no top-level create command. REST resource operations have native command paths generated from the same contract. Use the resource hierarchy and `help` command to discover the available paths. Authentication uses `nqd login` rather than resource commands. Body fields use kebab-case flags. The parser converts them to API field names and validates numbers, booleans, enums, and required fields from the contract. Common short flags are `-n` (`--name`), `-d` (`--description`), `-l` (`--limit`), `-s` (`--search`), `-o` (`--order`), `-c` (`--cursor`), `-w` (`--workspace`), `-j` (`--json`), `-b` (`--body`), `-q` (`--query`), and `-t` (`--type`). Command help lists the flags supported by each operation. Use `-h` or `--help` when an option-style help alias is more convenient. ```sh nqd entries create --name Hosting --unit-code hour --quantity 2.00 --price-per-unit 100.00 --currency-id currency_01J... nqd clients create --name Acme --type company ``` Invoice creation requires a currency, entries, and modifiers. Put the complete array body in a file so every required entry field is explicit. ```sh nqd invoices create --body @invoice.json ``` Each invoice entry in `invoice.json` requires `id`, `name`, `description`, `quantity`, `unit`, and `pricePerUnit`. The invoice body also requires `currencyId`, `entries`, and `modifiers`. When replacing a full invoice modifiers array, preserve each returned `appliedId` for an existing applied modifier, including repeated applications of the same catalog modifier. `appliedId` is the saved child snapshot ID; `catalogModifierId` identifies the catalog definition. Child modifier commands use `APPLIED_MODIFIER_ID` for the saved child. Recurring template creation has the same contract-driven requirements. Use `--body @template.json` with a complete payload instead of assuming that `--name` is enough. Use `--body ''` for a complete request body, or `--body @request.json` to read it from a file. Do not combine `--body` with individual body-field flags. Use `--entries` only when the selected operation exposes an entries body field. All commands support `--json` for scripts. Workspace lists preserve the API envelope and add `selectedWorkspaceId` plus a `selected` flag on each record. Webhook creation and rotation redact the one-time signing secret by default. Pass `--reveal-secrets` to `nqd webhooks create` or `nqd webhooks WEBHOOK_ID rotate` to receive it once, then save it in your receiver's secret manager. The flag is unavailable on other commands. The CLI does not save signing secrets in local workspace state. ### Manage integration retention Cleanup is disabled by default. Use `null` to retain a record type forever, or set a window from 1 through 3650 days. Preview supplies the policy revision required for an explicit bounded prune. Pending work, current retries, paused backlog, and referenced logs are protected; financial records are outside this policy. ```sh nqd integrations retention get nqd integrations retention update --body '{"enabled":true,"logRetentionDays":90,"deliveryRetentionDays":30}' nqd integrations retention preview nqd integrations retention prune --body '{"policyRevision":"REVISION_FROM_PREVIEW","maxRows":100,"confirm":"prune"}' ``` ### Select a workspace once List workspaces with `nqd workspaces`. Select one with `use`; the selection is saved under `~/.nqd` or the directory named by an absolute `NQD_HOME` value. The list marks the current workspace. The use command validates access before saving. ```sh nqd workspaces nqd workspaces use workspace_01J... nqd workspaces current ``` The selected workspace is used for later workspace-scoped commands. Pass `--workspace ` when one command needs a different workspace. `NQD_WORKSPACE_ID` remains available for automation. The per-call flag takes precedence over the environment variable and the saved selection. Workspace selection is stored separately for each API origin. OAuth tokens stay in the operating system credential manager. The CLI never writes tokens into `~/.nqd`. The generated-operation interface remains available for existing scripts and exact contract inspection. Use native commands for normal resource work. Use `nqd help` for global options, `nqd help ` for a resource, and `nqd help ` for an action. `-h` and `--help` remain accepted as aliases. Exit code 0 means success, 1 means an API failure, and 2 means usage, configuration, or authentication failure.