Usage

# List (with automatic cursor pagination)
factuarea invoices list --json
factuarea contacts list --paginate --json

# Get one
factuarea invoices show <uuid> --json

factuarea invoices create -d '{"client_id":"…","series_id":"…","lines":[…]}'

factuarea invoices send <uuid>
factuarea invoices mark-paid <uuid>

# 1) A read resolves the account by itself
#    (GET /v1/me, then GET /v1/accounts/<your account>/members)
factuarea account members list --json

# 2) A write must name it. Without the account it fails with code 2 and sends
#    nothing; with --account the request goes to POST /v1/accounts/<account>/webhooks
factuarea account webhooks create --url https://example.com/hooks --enabled-events account.member_added
factuarea account webhooks create --account <account> --url https://example.com/hooks --enabled-events account.member_added

# 3) A managed account is the resource: always the positional argument
#    (GET /v1/accounts/<managed_account>); --account does not fill it
factuarea managed-accounts show <managed_account> --json

# 4) A root provisioning route carries no account (POST /v1/accounts)
factuarea managed-accounts create --external-ref cliente-0042 --plan emprendedor \
  --tax-id B12345674 --legal-name "Talleres García SL" --confirm create

factuarea managed-accounts list --json
factuarea managed-accounts show <managed_account>
factuarea managed-accounts plan preview <managed_account> --plan empresario
factuarea managed-accounts plan update <managed_account> --plan empresario --confirm <managed_account>
factuarea managed-accounts access-level update <managed_account> --level view
factuarea managed-accounts claim-tokens create <managed_account> --send-email --confirm <managed_account>
factuarea managed-accounts management end <managed_account> --confirm <managed_account>

factuarea account webhooks list --json
factuarea account webhooks create --account <account> --url https://example.com/hooks \
  --enabled-events account.member_added --account-relationship own
factuarea account webhooks deliveries list <webhook> --status failed --json
factuarea account webhooks deliveries retry --account <account> <webhook> <delivery>
factuarea account request-logs list --only_errors true --json
factuarea account request-logs show <request_id> --json

# Clock an employee in and out — every entry is hash-chained (RD-ley 8/2019)
factuarea time-entries clock-in  -d '{"employee_id":"…","source":"web"}'
factuarea time-entries clock-out -d '{"employee_id":"…","source":"web"}'

# Request time off, then approve it
factuarea absence-requests create \
  -d '{"employee_id":"…","absence_type_id":"…","start_date":"2026-08-01","end_date":"2026-08-05"}'
factuarea absence-requests approve <uuid>

# Live team presence right now
factuarea presence live --json

# Close a month's immutable register, then export it (ITSS RD-ley 8/2019)
factuarea monthly-time-record-closes create -d '{"year":2026,"month":7}'
factuarea monthly-time-record-closes export <uuid> --format rdley_8_2019 --json

# What can be automated: triggers, operators and registered actions.
factuarea automations catalog show --json

# The evaluable fields of one trigger.
factuarea automations catalog trigger-fields invoice.paid --json

factuarea automations rules create --skeleton

{
  "actions": [],
  "conditions": {
    "<key>": "<string>"
  },
  "description": "<string>",
  "name": "<string>",
  "scope": "<empresa|cartera>",
  "trigger_type": "<string>"
}

# Fill it in and send it whole. `scope` is chosen here and cannot be changed later.
factuarea automations rules create --json -d '{
  "name": "Warn me on a large payment",
  "scope": "empresa",
  "trigger_type": "invoice.paid",
  "conditions": {"field": "total", "operator": "gte", "value": 1000},
  "actions": [
    {"type": "notify_in_app", "order": 0, "parameters": {
      "recipient_type": "role", "role": "admin", "category": "invoice",
      "title": "Large payment", "message": "An invoice over 1000 EUR has been paid"
    }}
  ]
}'

# Dry-run it against a sample event: it returns the trace per step and materialises nothing.
factuarea automations rules dry-run <rule_id> --json \
  -d '{"event_type":"invoice.paid","event_payload":{"total":1200,"status":"paid"}}'

# A rule is created in draft and fires nothing until you activate it.
factuarea automations rules activate <rule_id>
factuarea automations rules pause <rule_id>

# Read one, and edit it — every edit seals a new version.
factuarea automations rules show <rule_id> --json
factuarea automations rules update <rule_id> --json -d '{"name":"Warn me on a payment over 2000"}'

# List with filters, walking the cursor for you.
factuarea automations rules list --paginate --json
factuarea automations rules list --status active --trigger_type invoice.paid --json

# Only the portfolio rules: the ones that watch the account's other tax IDs.
factuarea automations rules list --scope cartera --json

# The sealed versions of the definition.
factuarea automations rules versions list <rule_id> --json
factuarea automations rules versions show <rule_id> 2 --json

# What fired, and what each step did.
factuarea automations runs list --paginate --json
factuarea automations runs list --automation_rule_id <rule_id> --status failed --json

# What a portfolio rule did on one of the tax IDs it watches.
factuarea automations runs list --subject_company_id <company_id> --json
factuarea automations runs show <run_id> --json
factuarea automations runs steps list <run_id> --json

# Consumption against the plan budget for the period.
factuarea automations usage show --json

# Replay runs the parked work again FOR REAL: it sends email and delivers webhooks.
factuarea automations runs replay <run_id> --confirm <run_id>
factuarea automations runs steps replay <run_id> 0 --confirm 0

# Deleting a rule stops it firing for good; its versions and runs stay auditable.
factuarea automations rules delete <rule_id> --confirm <rule_id>

# A project: its key (one letter plus up to nine letters or digits) prefixes the keys of its tasks (WEB-1, WEB-2…)
factuarea projects list --json
factuarea projects create --name "Web redesign" --key WEB --json
factuarea projects columns list <project_id> --json

# Create a task. The full body can also link it to a document or a contact in the
# same call with `entity_link` (invoice, quote, contact, product…).
factuarea tasks create --json -d '{
  "project_id": "<project_id>",
  "title": "Prepare the quote",
  "priority": "high",
  "due_on": "2026-10-15",
  "entity_link": {"type": "quote", "id": "<quote_id>"}
}'

# With flags, each custom field is `<field id>=<value>` and every value travels as text.
factuarea tasks create --project-id <project_id> --title "Call the customer" \
  --custom-fields <field_id>=42 --custom-fields <other_field_id>=high

# Commands take the UUID; resolve a key such as WEB-1 first.
factuarea tasks find-by-key WEB-1 --json

# Change its status: to a column of the project, or to a virtual state (`planned` is the backlog).
factuarea tasks status <task_id> --column-id <column_id>
factuarea tasks status <task_id> --status planned

# Search, walking the cursor for you.
factuarea tasks search --project_id <project_id> --status active --paginate --json

# The task labels of the company.
factuarea task-labels list --json

# Log time: a closed period (ISO 8601 with a time zone)…
factuarea tasks time-entries list <task_id> --paginate --json
factuarea tasks time-entries create <task_id> \
  --started-at 2026-09-28T09:00:00+02:00 --ended-at 2026-09-28T10:30:00+02:00 \
  --description "Quote review"

# …or with the timer of the key holder, who can have only one running.
factuarea tasks timer start <task_id>
factuarea task-timers current --json      # `{"data": null}` when nothing is running
factuarea task-timers stop --json

# Preview, then create, the draft invoice for the billable hours of a month.
factuarea projects time-invoices preview <project_id> \
  -d '{"period":{"from":"2026-09-01","to":"2026-09-30"},"grouping":"per_task"}' --json

# Deleting a column that has tasks needs a destination for them. It is irreversible: without
# an interactive terminal you must confirm with --confirm, and what you confirm is the LAST
# positional argument (here, the deleted column).
factuarea projects columns delete <project_id> <column_id> \
  --move_to_column_id <other_column_id> --confirm <column_id>

# Create a template in the company library: only --name is required.
factuarea pdf-templates create --company "$COMPANY_ID" \
  --name "Factura clásica" --base-preset classic --json

# Template lists paginate by page: one request per call, without --paginate.
factuarea pdf-templates list --company "$COMPANY_ID" --page 1 --per_page 20 --json

# Rename it, with the ETag of the last read as the If-Match precondition.
ETAG=$(factuarea pdf-templates find --company "$COMPANY_ID" "$TEMPLATE_ID" \
  --show-etag --json 2>&1 >/dev/null | sed -n 's/^etag: //p')
factuarea pdf-templates update --company "$COMPANY_ID" "$TEMPLATE_ID" \
  --name "Factura clásica 2026" --if-match "$ETAG" --json

# Pin that template on an invoice: expected_version is the selection_version
# of get-presentation…
factuarea invoices get-presentation --company "$COMPANY_ID" "$INVOICE_ID" --json
factuarea invoices assign-presentation --company "$COMPANY_ID" "$INVOICE_ID" \
  --template-id "$TEMPLATE_ID" --expected-version 1 --json

# …or hand the choice back to the defaults: template_id is required and accepts null.
factuarea invoices assign-presentation --company "$COMPANY_ID" "$INVOICE_ID" \
  --null-template-id --expected-version 2 --json

# Exact PDF of the invoice: prepare it from the id of its presentation, render it
# and download it.
factuarea pdf-artifacts prepare --company "$COMPANY_ID" --document-type invoice \
  --document-id "$INVOICE_ID" --presentation-id "$PRESENTATION_ID" \
  --purpose complete --format a4 --variant official --json
factuarea pdf-artifacts render --company "$COMPANY_ID" "$ARTIFACT_ID" --mode async --json
factuarea pdf-artifacts download --company "$COMPANY_ID" "$ARTIFACT_ID" -o invoice.pdf --show-etag

# Clear the description (null). --name is not passed, so the name is kept.
factuarea pdf-templates update --company "$COMPANY_ID" "$TEMPLATE_ID" \
  --null-description --if-match "$ETAG" --json

# Download a PDF
factuarea invoices pdf <uuid> -o invoice.pdf

# Upload a certificate (multipart)
factuarea verifactu certificates upload \
  -d '{"certificate_password":"…"}' --file-certificate_file cert.p12

# Import managed accounts in bulk (multipart). Each file goes with --file-<field>:
# `accounts_file` is required, `customers_file` is optional. Options travel in -d
# as a flat JSON object keyed by the form field names: only `options[send_email]`,
# `options[apply_customers_to_own_company]` and `options[confirm_plan_changes]`
# are accepted (booleans, `false` by default).
factuarea managed-accounts imports template -o template.csv
factuarea managed-accounts imports preview \
  --file-accounts_file accounts.csv --file-customers_file customers.csv   # writes nothing
factuarea managed-accounts imports create \
  --file-accounts_file accounts.csv --file-customers_file customers.csv \
  -d '{"options[send_email]":true}' --confirm create                     # irreversible

# Keep the ETag of the copy you download…
factuarea invoices pdf --company "$COMPANY_ID" "$INVOICE_ID" -o invoice.pdf --show-etag

# …and download it again only if it changed: a 304 leaves invoice.pdf untouched.
factuarea invoices pdf --company "$COMPANY_ID" "$INVOICE_ID" -o invoice.pdf \
  --if-none-match "$PDF_ETAG"

factuarea api get /v1/me --json
factuarea api post /v1/companies/acme_co/invoices -d '{…}'

factuarea commands --json

factuarea docs search invoice

factuarea docs list                    # every page: <path> — <title>
factuarea docs list /guides            # only the ones under that prefix
factuarea docs grep "idempotency-key"  # documentation sections that match
factuarea docs get /guides/idempotency # the whole page, as Markdown

factuarea api get /v1/companies/acme_co/stores