driptab/Docs
API

CLI reference

The Driptab CLI (dtab) is the primary way to manage billing resources, ingest test events, and apply configuration.

Install:

npm install -g @dotlabshq/dtab

Global flags

Flag Description
--api <url> Override the API base URL
--token <token> Use this token for the request (overrides stored token)
--project <id> Project ID to use (overrides context)
--json Output raw JSON
--help Show help for a command

Authentication

dtab token set <token>

Store an API token for subsequent commands.

dtab token set dtab_f36951fb6dd443babd9df35d32ae1e0f

The token is saved to ~/.dtab/config.json.

dtab token create

Create a new API token.

dtab token create --name "MCP Agent" --scopes read
dtab token create --name "Backend"   --scopes read,write
Flag Required Description
--name <name> Yes Display name
--scopes <scopes> No Comma-separated: read, write. Default: read,write
--org <org_id> Conditional Organization ID (required if not set in context)

dtab token list

List all tokens for the current organization.

dtab token revoke <id>

Revoke a token by ID.

dtab whoami

Show the current authentication context.

Context

dtab use <org>/<workspace>/<project>

Set the active org/workspace/project context.

dtab use acme/default/billing

dtab ls

List orgs, workspaces, and projects with the active context highlighted.

Customers

dtab cust create

dtab cust create \
  --external-id <your-id> \
  --name "Jane Smith" \
  --email jane@example.com \
  --currency USD
Flag Required Description
--external-id <id> Yes Your system's stable ID for this customer
--name <name> No Display name
--email <email> No Email address
--currency <code> No ISO-4217 currency override

dtab cust list

List customers in the current project.

dtab cust get <id>

Get a customer by ID or external ID (ext:<your-id>).

Several commands accept friendly references and resolve them before calling the API:

  • customers: UUID or ext:<external_id>;
  • plans: UUID or plan code;
  • add-ons: UUID, short ID, or add-on code;
  • metrics in plans add-charge: UUID or metric code.

Metrics

dtab metrics create

dtab metrics create \
  --code mail_out \
  --name "Outbound Emails" \
  --aggregation-type sum \
  --field count
Flag Required Description
--code <code> Yes Stable identifier
--name <name> Yes Display name
--aggregation-type <type> Yes sum, count, count_unique, max, latest
--field <field> Conditional Event property to aggregate (required for sum, max, count_unique)

dtab metrics list

dtab metrics get <id>

Plans

dtab plans create

dtab plans create \
  --code pro-monthly \
  --name "Pro Monthly" \
  --interval monthly \
  --amount 2900 \
  --currency USD \
  --labels domain,reseller \
  --category hosting
Flag Required Description
--code <code> Yes Stable identifier
--name <name> Yes Display name
--interval <interval> Yes weekly, monthly, quarterly, semiannual, yearly
--amount <cents> No Base fee in smallest currency unit. Default 0.
--currency <code> Yes ISO-4217
--description <text> No Optional description
--labels <list> No Comma-separated labels e.g. domain,reseller
--category <category> No Plan category

dtab plans update <plan_id|code>

Update labels, category, or name on an existing plan.

dtab plans update <plan_id|code> --labels domain,vps,managed
dtab plans update <plan_id|code> --category hosting
dtab plans update <plan_id|code> --name "New Name"
Flag Required Description
--labels <list> No Comma-separated labels (replaces existing)
--category <category> No Plan category
--name <name> No Display name
--description <text> No Description

At least one flag required.

dtab plans add-charge <plan_id|code>

Add a usage-based charge to an existing plan. The plan and metric arguments can be UUIDs or stable codes.

dtab plans add-charge pro-monthly \
  --model standard \
  --metric api_calls \
  --rate 0.0015 \
  --timing arrears
Flag Required Description
--model <model> No standard. Default standard
--metric <id_or_code> Yes Billable metric UUID or code
--rate <decimal> Yes Per-unit price as decimal string
--timing <timing> No immediate or arrears. Default arrears.

For flat-fee catalog charges, define the plan in driptab.yaml and apply it with dtab sync.

dtab plans list

Lists plans with a LABELS column.

dtab plans get <id>

Output includes labels and category fields.

dtab plans archive <id>

Archive a plan. Fails if the plan has active subscriptions.

Catalog

dtab catalog upsert

dtab catalog upsert \
  --code tld.com.register \
  --name ".com Registration" \
  --amount 1200 \
  --currency USD
Flag Required Description
--code <code> Yes Stable key ([a-z0-9._-]+)
--name <name> Yes Display name
--amount <cents> Yes Price in smallest currency unit
--currency <code> No ISO-4217. Default USD.
--metadata <json> No JSON metadata string

dtab catalog list

dtab catalog get <id>

dtab catalog archive <id>

Archive a catalog item. Fails if referenced by active charges or add-ons.

Add-ons

dtab addons list

dtab addons apply <addon_code>

Apply an add-on to a customer, generating an immediate invoice.

dtab addons apply domain-transfer-com --customer ext:acme-user-1234

The add-on argument may be an ID, short ID, or add-on code.

Subscriptions

dtab subs create

dtab subs create \
  --external-id your-sub-id \
  --customer ext:your-customer-id \
  --plan <plan_code_or_id>
Flag Required Description
--external-id <id> Yes Your stable subscription identifier
--customer <id> Yes Customer ID or ext:<external_id>
--plan <id> Yes Plan ID or code
--properties <json> No JSON object of subscription properties

dtab subs list

List subscriptions. Filter by customer ID or external ID:

dtab subs list --customer ext:acme-user-1234

dtab subs get <id>

dtab subs update <id>

Update subscription status or properties.

dtab subs update <id> --status suspended
dtab subs update <id> --prop domain=example.com
Flag Required Description
--status <status> No active, suspended, terminated, or canceled
--prop <key=value> No Property to merge. Repeatable.

At least one flag required.

dtab subs terminate <id>

Terminate a subscription. Invoices the current period and stops future billing.

dtab subs suspend <id>

Suspend a subscription. Events are rejected while suspended.

Events

dtab ev ingest

dtab ev ingest \
  --transaction-id <unique_id> \
  --subscription ext:<your-sub-id> \
  --code <metric_code> \
  --value 1
Flag Required Description
--transaction-id <id> Yes Unique event ID (idempotency key)
--subscription <id> Yes Subscription ID or ext:<id>
--code <code> Yes Billable metric code
--value <n> No Numeric value (decimal string). Default 1.
--timestamp <iso> No When the event occurred. Default: now.
--prop <key=value> No Additional properties. Repeatable.

Invoices

dtab inv list

List invoices. Filter by customer ID or external ID:

dtab inv list --customer ext:acme-user-1234

dtab inv get <id_or_number>

Payments

dtab payments record

dtab payments record \
  --invoice INV-2026-0001 \
  --amount 847 \
  --currency USD \
  --provider stripe \
  --provider-id pi_3abc123
Flag Required Description
--invoice <id_or_number> Yes Invoice ID or number
--amount <cents> Yes Amount in smallest currency unit
--currency <code> Yes ISO-4217
--provider <name> No manual, stripe, iyzico, paytr. Default manual.
--provider-id <id> No External payment reference
--paid-at <iso> No When payment was confirmed. Default: now.
--reference <text> No Internal reference note

Webhooks

dtab webhooks create

dtab webhooks create \
  --url https://app.example.com/hooks/driptab \
  --events invoice.created,payment.succeeded

dtab webhooks list

dtab webhooks delete <id>

dtab webhooks deliveries

dtab webhooks deliveries --endpoint <id>

Cache

dtab cache purge [customerId]

Alias: dtab cc

Purge portal cache entries.

dtab cache purge <customerId>   # purge single customer cache
dtab cache purge                # purge all portal caches

Analytics

dtab analytics

Show billing analytics for the current project.

dtab analytics

Active subscriptions   42
MRR                    $1,299.00
Outstanding invoices   3  ($450.00)
Revenue (30d)          $8,900.00
Payments (30d)         28

GitOps sync

dtab sync

Apply driptab.yaml to the current project.

dtab sync                         # apply driptab.yaml in current directory
dtab sync path/to/file.yaml
dtab sync path/to/file.yaml --dry-run
dtab sync --dry-run               # preview without applying

Audit

dtab audit events

Query the billing events log.

dtab audit events --resource-type customer
dtab audit events --event-type plan.archived
dtab audit events --since 2026-06-01

dtab audit logs

Query the HTTP access log.

dtab audit logs --token-id <id>
dtab audit logs --status 403