> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getlago.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Command reference

> Every Lago CLI command group, one page each, with the request on the left and the output on the right.

Commands follow one shape:

```bash theme={"dark"}
lago <resource> <action> [identifier] [flags]
```

Every command answers `--help` with its full flag list. Four rules apply everywhere:

* **Flags are API fields.** A `snake_case` field becomes a `--kebab-case` flag. Nested fields carry their parent as a prefix: `billing_configuration.payment_provider` is `--billing-configuration-payment-provider`.
* **Objects and arrays take JSON.** `--metadata '[{"key":"tier","value":"gold","display_in_invoice":false}]'`.
* **`--input` takes the whole body.** Inline JSON or `@file.json`. Use it for deeply nested payloads such as plan charges. The body is wrapped exactly as the API expects.
* **Identifiers are positional**, and their kind depends on the resource. Passing the wrong kind returns a not-found error that names the resource type, exit code 4.

| Resource                                                                                             | Positional identifier          |
| ---------------------------------------------------------------------------------------------------- | ------------------------------ |
| customers, customer wallets, payment methods                                                         | `external_customer_id` (yours) |
| subscriptions                                                                                        | `external_id` (yours)          |
| billable metrics, plans, coupons, add-ons, taxes, features, billing entities                         | `code`                         |
| invoices, credit notes, fees, payments, payment requests, wallets, webhook endpoints, quotes, orders | `lago_id` (Lago's UUID)        |
| events                                                                                               | `transaction_id`               |

## Output on these pages

The right column shows what each command prints. Creates and updates print the identifier block by default. Reads print the full resource, shown here as `--output json` because that is the form to script against. Response bodies follow the Lago API schema, so the [API reference](/api-reference/intro) documents every field.

The global flags (`--output`, `--query`, `--dry-run`, `--confirm`, `--profile`, `--mode`), exit codes, pagination, and safety gates are covered in the [Lago CLI overview](/guide/lago-cli/overview).

## Command groups

<CardGroup cols={2}>
  <Card title="Setup and diagnostics" href="/guide/lago-cli/commands/setup">init, whoami, doctor, version, upgrade, completion</Card>
  <Card title="Helpers" href="/guide/lago-cli/commands/helpers">api, docs, alias, seed, fixtures, logs tail</Card>
  <Card title="Billable metrics" href="/guide/lago-cli/commands/billable-metrics">Define what you meter.</Card>
  <Card title="Plans" href="/guide/lago-cli/commands/plans">Plans, charges, fixed charges, filters, metadata.</Card>
  <Card title="Features and entitlements" href="/guide/lago-cli/commands/features-and-entitlements">Features, privileges, plan entitlements, subscription overrides.</Card>
  <Card title="Customers" href="/guide/lago-cli/commands/customers">Customers, current and past usage, portal and checkout URLs.</Card>
  <Card title="Subscriptions" href="/guide/lago-cli/commands/subscriptions">Assign, override, alert, terminate.</Card>
  <Card title="Events" href="/guide/lago-cli/commands/events">Send one, stream NDJSON, batch, estimate.</Card>
  <Card title="Invoices" href="/guide/lago-cli/commands/invoices">List, preview, finalize, void, download, payment URL.</Card>
  <Card title="Credit notes" href="/guide/lago-cli/commands/credit-notes">Estimate, issue, void.</Card>
  <Card title="Coupons and add-ons" href="/guide/lago-cli/commands/coupons-and-add-ons">Discounts and one-off items.</Card>
  <Card title="Wallets" href="/guide/lago-cli/commands/wallets">Prepaid credits, top-ups, alerts.</Card>
  <Card title="Taxes and fees" href="/guide/lago-cli/commands/taxes-and-fees">Tax rates and fee inspection.</Card>
  <Card title="Payments" href="/guide/lago-cli/commands/payments">Payments, requests, receipts, payment methods.</Card>
  <Card title="Webhooks" href="/guide/lago-cli/commands/webhooks">Endpoints and signature keys.</Card>
  <Card title="Analytics and logs" href="/guide/lago-cli/commands/analytics-and-logs">MRR, revenue, usage, audit and API logs.</Card>
  <Card title="Organization" href="/guide/lago-cli/commands/organization">Organization settings and billing entities.</Card>
  <Card title="Quotes and orders" href="/guide/lago-cli/commands/quotes-and-orders">Quotes, order forms, orders.</Card>
</CardGroup>

<RequestExample>
  ```bash Shape theme={"dark"}
  lago customers create --external-id acme_001 --name "Acme Inc." --currency USD
  lago customers get acme_001
  lago customers get acme_001 --output json --query 'customer.email'
  lago customers list --limit 5
  lago customers delete acme_001 --confirm acme_001
  ```

  ```bash Wrong identifier kind theme={"dark"}
  # A plan code passed where a subscription external ID belongs
  lago events send --external-subscription-id ai_plan_gpt4_tokens --code api_calls
  echo $?
  ```
</RequestExample>

<ResponseExample>
  ```text Create theme={"dark"}
  LAGO_ID      1a901a90-1a90-1a90-1a90-1a901a901a90
  EXTERNAL_ID  acme_001
  NAME         Acme Inc.
  ```

  ```json Get theme={"dark"}
  {
    "customer": {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "sequential_id": 1,
      "slug": "LAG-1234-001",
      "external_id": "acme_001",
      "billing_entity_code": "acme_corp",
      "address_line1": "5230 Penfield Ave",
      "address_line2": null,
      "applicable_timezone": "America/Los_Angeles",
      "city": "Woodland Hills",
      "country": "US",
      "currency": "USD",
      "email": "billing@acme.example",
      "legal_name": "Coleman-Blair",
      "legal_number": "49-008-2965",
      "logo_url": "http://hooli.com/logo.png",
      "name": "Acme Inc.",
      "firstname": "Gavin",
      "lastname": "Belson",
      "account_type": "customer",
      "customer_type": "company",
      "phone": "1-171-883-3711 x245",
      "state": "CA",
      "tax_identification_number": "EU123456789",
      "timezone": "America/New_York",
      "url": "http://hooli.com",
      "zipcode": "91364",
      "net_payment_term": 30,
      "external_salesforce_id": "0015p00001JQx1QAAT",
      "created_at": "2022-04-29T08:59:51Z",
      "updated_at": "2022-04-29T08:59:51Z",
      "finalize_zero_amount_invoice": "inherit",
      "skip_invoice_custom_sections": false,
      "billing_configuration": {
        "invoice_grace_period": 3,
        "subscription_invoice_issuing_date_anchor": "next_period_start",
        "subscription_invoice_issuing_date_adjustment": "keep_anchor",
        "payment_provider": "stripe",
        "payment_provider_code": "stripe-eu-1",
        "provider_customer_id": "cus_12345",
        "sync": true,
        "sync_with_provider": true,
        "document_locale": "fr",
        "provider_payment_methods": [
          "card",
          "sepa_debit",
          "us_bank_account",
          "bacs_debit",
          "link",
          "boleto",
          "crypto",
          "customer_balance"
        ]
      },
      "shipping_address": {
        "address_line1": "5230 Penfield Ave",
        "address_line2": null,
        "city": "Woodland Hills",
        "country": "US",
        "state": "CA",
        "zipcode": "91364"
      },
      "metadata": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "key": "Purchase Order",
          "value": "123456789",
          "display_in_invoice": true,
          "created_at": "2022-04-29T08:59:51Z"
        }
      ],
      "integration_customers": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "type": "netsuite",
          "integration_code": "netsuite-eu-1",
          "external_customer_id": "cus_12345",
          "sync_with_provider": true,
          "subsidiary_id": "2",
          "targeted_object": "contacts",
          "email": "dinesh@piedpiper.test"
        }
      ],
      "taxes": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "name": "TVA",
          "code": "french_standard_vat",
          "description": "French standard VAT",
          "rate": 20,
          "applied_to_organization": true,
          "created_at": "2023-07-06T14:35:58Z"
        }
      ],
      "applicable_invoice_custom_sections": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "name": "EU Bank Details",
          "code": "eu_bank_details",
          "description": "This section contains the bank details for EU customers.",
          "details": "Bank Name: Lago Bank, IBAN: FR7630004000031234567890143",
          "display_name": "Bank Details:",
          "applied_to_organization": true,
          "organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "created_at": "2023-07-06T14:35:58Z"
        }
      ],
      "error_details": [
        {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "error_code": "tax_error",
          "details": {
            "tax_error": "taxDateTooFarInFuture"
          }
        }
      ]
    }
  }
  ```

  ```json Query theme={"dark"}
  "dinesh@piedpiper.test"
  ```

  ```text Wrong identifier kind theme={"dark"}
  Error: no subscription "ai_plan_gpt4_tokens" exists in this organization
  Suggestion: Check that each identifier is the right kind for the flag it was passed to: a plan code is not a subscription external ID, and a Lago ID is not an external ID.
  $ echo $?
  4
  ```
</ResponseExample>