CLI

@alyabooks/cli is a thin, dependency-free command-line client for the REST API. Use it for scripts, cron jobs and CI pipelines; use the MCP server for AI-driven workflows.

Install and configure

npm install -g @alyabooks/cli        # Node.js 18 or later
alyabooks config set api-key sk_live_…
alyabooks config get                 # key is masked
alyabooks me

Configuration is stored in ~/.alyabooks/config.json (mode 600). Environment variables win over the file, and --api-key, --api-url, --organization win for one call.

Output

Commands print a table (lists) or key/value lines (single objects). --json prints the raw response:

alyabooks invoice list                                    # table + "page 1 of 3 · 57 items"
alyabooks invoice list --json | jq '.data[].invoiceNumber'

Exit codes: 0 success, 1 usage error or partial failure (batch results are printed), 2 API error, 3 authentication error (401).

Commands

invoice

alyabooks invoice list --status accepted --start-issue-date 2026-01-01 --per-page 50 --sort issueDate --order desc
alyabooks invoice create -f invoice.json            # file = one invoice, an array, or { invoices: [...] }
alyabooks invoice create -f invoice.json --wait     # poll status until accepted/rejected
alyabooks invoice get 3f2e…
alyabooks invoice status 3f2e…
alyabooks invoice validation 3f2e…
alyabooks invoice validate 3f2e…
alyabooks invoice submit 3f2e… --wait --wait-timeout 120000
alyabooks invoice send 3f2e… --to ap@buyer.ae --cc me@seller.ae --subject "Invoice INV-0042"
alyabooks invoice download 3f2e… --format xml|pdf|html -o INV-0042.xml
alyabooks invoice payments 3f2e…
alyabooks invoice pay 3f2e… --amount 5250 --date 2026-10-01 --method bank_transfer --reference "TRF 123"
alyabooks invoice delete 3f2e…

Filters map one-to-one onto the API query parameters in kebab-case: --payment-status, --document-kind, --buyer-id, --include-archived, --is-test, --external-id, --keyword.

number

alyabooks number next --series credit_note
alyabooks number verify --value INV-0043
alyabooks number settings
alyabooks number set --template "INV-{YYYY}-{n}" --pad-length 5 --reset-yearly

import (incoming invoices)

alyabooks import incoming -f supplier.xml --wait     # XML is sent as text, other files as base64
alyabooks import incoming -f scan.pdf --reference PO-4711
alyabooks import list --status failed
alyabooks import invoices --payment-status unpaid
alyabooks import get 9a1b…
alyabooks import status 9a1b…
alyabooks import validation 9a1b…
alyabooks import content 9a1b… --part lineitems|seller|buyer|delivery|taxes|paymentterms|paymentmeans|summary
alyabooks import source 9a1b… -o original.xml
alyabooks import update 9a1b… -f fix.json      # correct a draft: seller, buyer, delivery, lineItems, vatBreakdown, paymentMeans…
alyabooks import accept 9a1b…
alyabooks import reject 9a1b… --reason "Duplicate of INV-2201"
alyabooks import pay 9a1b… --amount 1050
alyabooks import delete 9a1b…

customer / product

alyabooks customer list --keyword buyer --type buyer
alyabooks customer get <id>
alyabooks customer create -f customer.json
alyabooks customer update <id> -f patch.json
alyabooks customer delete <id>
alyabooks customer next-number
alyabooks customer import -f customers.json           # array or { customers: [...] }

alyabooks product list --sku CONS-H
alyabooks product create -f product.json
alyabooks product valid-code --sku CONS-H
alyabooks product import -f products.json

webhook

alyabooks webhook list
alyabooks webhook events
alyabooks webhook create --url https://example.com/hooks --events invoice.reported,invoice.paid --name erp
alyabooks webhook update <id> --events "*" --no-active
alyabooks webhook test <id>
alyabooks webhook deliveries <id> --status failed
alyabooks webhook retry <id> <deliveryId>
alyabooks webhook rotate-secret <id>
alyabooks webhook delete <id>

fields, me, config

alyabooks fields list --level line
alyabooks fields templates --document-kind invoice
alyabooks me
alyabooks config path

In CI

# GitHub Actions: report the month's invoices produced by your billing job
- run: npm install -g @alyabooks/cli
- run: alyabooks invoice create -f out/invoices.json --wait --json > result.json
  env:
    ALYABOOKS_API_KEY: ${{ secrets.API_KEY }}

The command exits non-zero when any element failed, and result.json contains the per-element results for reconciliation.