# CLI

> @alyabooks/cli: manage invoices, imports, customers, products and webhooks from the terminal or CI.

Source: /docs/guides/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](/docs/guides/mcp-server) for AI-driven workflows.

## Install and configure

```bash
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
```

| Setting | `alyabooks config set …` | Environment variable |
| --- | --- | --- |
| API key | `api-key <key>` | `ALYABOOKS_API_KEY` |
| API URL | `api-url <url>` | `ALYABOOKS_API_URL` (default `https://api.alyabooks.ai/api/v1`; a Supabase project URL is accepted and completed) |
| Client organization | `organization <id>` | `ALYABOOKS_ORGANIZATION_ID` (CA firms) |

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:

```bash
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

```bash
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

```bash
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)

```bash
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

```bash
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

```bash
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

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

## In CI

```yaml
# 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.