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

# CLI

> La herramienta oficial de línea de comandos de Commet. Gestioná billing, reenviá webhooks y automatizá tu workflow desde la terminal.

> La herramienta oficial de línea de comandos de Commet. Gestioná billing, reenviá webhooks y automatizá tu workflow desde la terminal.

## Instalar

<Tabs>
  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add -g commet
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g commet
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn global add commet
    ```
  </Tab>
</Tabs>

Requiere Node.js 18+.

## Autenticación

**`commet login`**

Autenticá vía navegador. Abre un flujo device-code y guarda tu token en `~/.commet/auth.json`.

```bash theme={null}
commet login
```

En CI, configurá `COMMET_API_KEY` como variable de entorno en su lugar.

El CLI usa dos tipos de credenciales, según el comando:

| Tipo de comando | Resolución de credenciales |
| - | - |
| Comandos de recursos (`customers`, `plans`, `subscriptions`, `usage`, …) | Variable `COMMET_API_KEY` → API key de proyecto (auto-generada por `commet link`, guardada en `.commet/config.json`) → error |
| Comandos de plataforma (`orgs`, `link`, `listen`, `create`) | Variable `COMMET_API_KEY` → credenciales guardadas de `commet login` |

Los comandos de recursos nunca caen en las credenciales de `commet login` — sin una API key del entorno o de un proyecto vinculado, fallan y te indican correr `commet link`.

```bash theme={null}
commet logout     # Eliminar credenciales almacenadas
```

## Setup

**`commet agents setup`**

Prepará un repositorio existente para agentes de código. El comando preserva el resto de `AGENTS.md` y administra únicamente su propio bloque delimitado, por lo que podés volver a ejecutarlo o quitarlo más adelante.

```bash theme={null}
commet agents setup
commet agents setup --check --output agent
```

Usá `--check --output agent` en workflows automatizados para verificar que las instrucciones administradas estén al día sin reescribir el archivo.

**`commet doctor`**

Revisá el SDK instalado, la configuración del proyecto, las instrucciones del agente y el entorno local antes de pedirle que implemente billing. Doctor es de solo lectura: no se conecta con Commet, no modifica archivos y no imprime secretos.

```bash theme={null}
commet doctor
commet doctor --output agent
```

El output para agentes es compacto y sirve como contexto para una tarea de implementación. Para la guía del SDK que coincide con la versión instalada, empezá por `node_modules/@commet/node/docs/README.md`.

**`commet link`**

Vinculá este proyecto a una organización de Commet. Volvé a ejecutarlo para cambiar de organización.

```bash theme={null}
commet link
```

```bash theme={null}
commet link --org acme       # Por slug o ID
commet link --clear          # Desvincular proyecto
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--org <slug-o-id>` | No | Slug o ID de la organización. Salta la selección interactiva |
| `--clear` | No | Desvincular el proyecto de su organización |

**`commet pull`**

Descargá tu configuración de billing y generá `commet.config.ts` con features y planes tipados.

```bash theme={null}
commet pull
```

```bash theme={null}
commet pull --dry-run        # Vista previa sin escribir archivos
commet pull --yes            # Saltar confirmación
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--dry-run` | No | Mostrar qué cambiaría sin escribir ningún archivo |
| `-y, --yes` | No | Saltar el prompt de confirmación |

Después de `commet pull`, tus llamadas al SDK tienen autocompletado para plan codes y feature codes.

**`commet push`**

Subí tu `commet.config.ts` local a Commet. Crea o actualiza features y planes para que coincidan con tu config.

```bash theme={null}
commet push
```

```bash theme={null}
commet push --dry-run        # Vista previa de qué cambiaría en remoto
commet push --yes            # Push sin confirmación
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--dry-run` | No | Mostrar qué cambiaría sin aplicar nada |
| `-y, --yes` | No | Saltar el prompt de confirmación |

<Warning>
  Los cambios de tipo de feature (`boolean` a `usage`, etc.) están bloqueados vía push. Cambialos desde el dashboard.
</Warning>

**`commet create`**

Creá un nuevo proyecto de Commet desde un template. Crea planes y features en tu organización sandbox, genera una API key y vincula el proyecto.

```bash theme={null}
commet create
```

```bash theme={null}
commet create myapp -t metered --org acme -y
commet create --list              # Listar templates disponibles
```

| Flag | Requerido | Descripción |
| - | - | - |
| `-t, --template <nombre>` | No | Template: `fixed`, `seats`, `metered`, `credits`, `balance-ai`, `balance-fixed` |
| `--org <slug>` | No | Slug o ID de la organización sandbox |
| `--skills` | No | Instalar agent skills |
| `--no-skills` | No | Saltar la instalación de agent skills |
| `-y, --yes` | No | Aceptar defaults en los prompts opcionales |
| `--ref <ref>` | No | Ref de git de donde traer los templates. Default: `main` |

**`commet listen`**

Reenviá eventos de webhook desde Commet a tu servidor local. Sin necesidad de ngrok ni herramientas de tunneling externas.

```bash theme={null}
commet listen 3000
```

El argumento acepta un puerto, host:port, o URL completa:

```bash theme={null}
commet listen 3000                              # http://localhost:3000/
commet listen localhost:3000/webhooks            # http://localhost:3000/webhooks
commet listen http://local.commet.co:3010/api    # http://local.commet.co:3010/api
```

Filtrá por tipo de evento:

```bash theme={null}
commet listen 3000 --events invoice.created,subscription.activated
```

| Flag | Requerido | Descripción |
| - | - | - |
| `<url>` | Sí | URL destino: puerto (`3000`), host:port, o URL completa |
| `--events <tipos>` | No | Tipos de evento a reenviar, separados por coma |

```
  ✓ Authenticated (org: Acme Inc)
  ✓ Connected to Commet webhook stream
  ⟶ Forwarding to http://localhost:3000/
  ⟶ Signing secret: whsec_...

  Ready! Listening for webhook events...

  14:32:01  customer.created              →  200 OK     (12ms)
  14:32:05  subscription.updated          →  200 OK     (8ms)
```

La sesión queda abierta hasta `Ctrl+C`. Los eventos están firmados con el secret mostrado.

```bash theme={null}
commet orgs               # Listar organizaciones (nombre, slug, modo)
```

## Customers

Creá y gestioná clientes, consultá detalles y manejá operaciones en batch.

**`commet customers create`**

Creá un cliente.

```bash theme={null}
commet customers create --email user@acme.com --id user_123
```

```bash theme={null}
commet customers create \
  --email billing@corp.com \
  --full-name "Acme Corp" \
  --metadata '{"plan":"enterprise"}'
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--email <email>` | Sí | Email de facturación |
| `--id <id>` | No | ID de cliente personalizado |
| `--external-id <id>` | No | ID de tu sistema |
| `--full-name <nombre>` | No | Nombre completo |
| `--tax-document <valor>` | No | Documento fiscal |
| `--timezone <tz>` | No | Timezone |
| `--metadata <json>` | No | Metadata como objeto JSON |
| `--address <json>` | No | Dirección como JSON: `{line1, city, postalCode, country}` |
| `--address-id <id>` | No | ID de una dirección existente del cliente |

```bash theme={null}
commet customers get --id cus_xxx                   # Obtener un cliente por ID
commet customers update --id cus_xxx --email new@acme.com  # Actualizar un cliente
commet customers list                                # Listar todos los clientes
commet customers list --limit 25 --cursor cur_xxx    # Paginar
commet customers list --external-id user_123         # Buscar por ID externo
commet customers create-batch --customers '[{"email":"a@co.com"},{"email":"b@co.com"}]'
```

## Subscriptions

Creá, cancelá y gestioná suscripciones. Cambiá planes, activá addons y manejá operaciones de balance.

**`commet subscriptions create`**

Creá una suscripción para un cliente.

```bash theme={null}
commet subscriptions create \
  --customer-id user_123 \
  --plan-code pro \
  --billing-interval monthly
```

```bash theme={null}
commet subscriptions create \
  --customer-id user_123 \
  --plan-id pln_xxx \
  --price-id pp_argentina \
  --billing-interval yearly \
  --initial-seats '{"team_member":5}' \
  --skip-trial true
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--customer-id <id>` | Sí | ID del cliente |
| `--plan-code <code>` | Uno de `plan-code` / `plan-id` | Código del plan |
| `--plan-id <id>` | Uno de `plan-code` / `plan-id` | ID del plan |
| `--billing-interval <interval>` | No | `weekly`, `monthly`, `quarterly`, `yearly`, `one_time` |
| `--price-id <id>` | No | Precio seleccionable del plan. Omitilo para usar el default del intervalo y sus precios por mercado |
| `--initial-seats <json>` | No | Asientos iniciales como JSON: `{featureCode: count}` |
| `--skip-trial <bool>` | No | Saltar el período de prueba |
| `--custom-trial-days <n>` | No | Sobrescribir la duración de prueba del catálogo |
| `--offer-id <id>` | No | Aplicar una Offer directamente. No se combina con `promo-code` ni con una prueba personalizada |
| `--promo-code <code>` | No | Aplicar la Offer referenciada por un código ingresado por el customer |
| `--provider <provider>` | No | Override del proveedor del checkout inicial: `stripe`, `commet` o `dlocal` |
| `--name <nombre>` | No | Nombre de la suscripción |
| `--start-date <date>` | No | Fecha de inicio (ISO 8601) |
| `--success-url <url>` | No | URL de redirección tras el checkout exitoso |

**`commet subscriptions cancel`**

Cancelá una suscripción. Por default cancela al final del período.

```bash theme={null}
commet subscriptions cancel --id sub_xxx
```

```bash theme={null}
commet subscriptions cancel --id sub_xxx --immediate true --reason "Customer requested"
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--id <id>` | Sí | ID de la suscripción |
| `--reason <razón>` | No | Motivo de cancelación |
| `--immediate <bool>` | No | Cancelar inmediatamente en vez de al final del período |

```bash theme={null}
commet subscriptions get-active --customer-id user_123           # Suscripción activa
commet subscriptions uncancel --id sub_xxx                       # Revertir cancelación pendiente
commet subscriptions reactivate --id sub_xxx --offer-id ofr_xxx  # Reactivar una suscripción cancelada con una Offer directa
commet subscriptions change-plan --id sub_xxx --new-plan-id pln_xxx --new-billing-interval yearly  # Cambiar de plan
commet subscriptions list                                            # Listar todas las suscripciones
commet subscriptions list --customer-id user_123 --status active     # Filtrar por cliente/estado
commet subscriptions preview-change --id sub_xxx --plan-id pln_xxx --billing-interval yearly  # Preview de prorrateo
commet subscriptions activate-addon --id sub_xxx --addon-id adn_xxx
commet subscriptions deactivate-addon --id sub_xxx --addon-id adn_xxx
commet subscriptions adjust-balance --id sub_xxx --amount 1000 --type balance --reason "Courtesy credit"
commet subscriptions topup-balance --id sub_xxx --amount 5000
commet subscriptions purchase-credits --id sub_xxx --credit-pack-id cpk_xxx
```

## Plans

Creá planes, adjuntá features y precios, y configurá precios regionales.

**`commet plans create`**

Creá un plan.

```bash theme={null}
commet plans create --name "Pro" --code pro
```

```bash theme={null}
commet plans create \
  --name "Developer" \
  --code developer \
  --consumption-model metered \
  --is-public true \
  --block-on-exhaustion true
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--name <nombre>` | Sí | Nombre del plan |
| `--code <code>` | Sí | Código del plan |
| `--description <desc>` | No | Descripción del plan |
| `--consumption-model <model>` | No | `metered`, `credits`, o `balance` |
| `--is-public <bool>` | No | Si el plan es visible públicamente |
| `--is-free <bool>` | No | Si el plan es gratuito |
| `--block-on-exhaustion <bool>` | No | Bloquear uso cuando se agota el balance/créditos |
| `--plan-group-id <id>` | No | ID del grupo de planes |
| `--metadata <json>` | No | Metadata como objeto JSON |

**`commet plans add-feature`**

Agregá una feature a un plan con pricing y límites.

```bash theme={null}
commet plans add-feature \
  --plan-id pln_xxx \
  --feature-id ftr_xxx \
  --included-amount 1000 \
  --overage-enabled true \
  --overage-unit-price 100
```

```bash theme={null}
commet plans add-feature \
  --plan-id pln_xxx \
  --feature-id ftr_xxx \
  --pricing-mode ai_model \
  --margin 30
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--plan-id <id>` | Sí | ID del plan |
| `--feature-id <id>` | Sí | ID de la feature |
| `--enabled <bool>` | No | Si la feature está habilitada |
| `--included-amount <n>` | No | Cantidad incluida de uso |
| `--unlimited <bool>` | No | Uso ilimitado |
| `--overage-enabled <bool>` | No | Habilitar cobro por excedente |
| `--overage-unit-price <n>` | No | Precio por unidad excedente (pricing `fixed`) |
| `--pricing-mode <mode>` | No | `fixed` o `ai_model` |
| `--margin <n>` | No | Porcentaje de margen (pricing `ai_model`) |
| `--credits-per-unit <n>` | No | Créditos por unidad |

**`commet plans add-price`**

Agregá un precio a un plan.

```bash theme={null}
commet plans add-price \
  --plan-id pln_xxx \
  --billing-interval monthly \
  --price 2900
```

```bash theme={null}
commet plans add-price \
  --plan-id pln_xxx \
  --billing-interval yearly \
  --price 29000 \
  --trial-days 14
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--plan-id <id>` | Sí | ID del plan |
| `--billing-interval <interval>` | Sí | `weekly`, `monthly`, `quarterly`, `yearly`, `one_time` |
| `--price <n>` | Uno de `price` / `inherits-from-price-id` | Precio base en la unidad menor de la moneda |
| `--inherits-from-price-id <id>` | Uno de `price` / `inherits-from-price-id` | Precio base heredado por una variante seleccionable |
| `--trial-days <n>` | No | Período de prueba en días |
| `--is-default <bool>` | No | Establecer como precio default |
| `--included-balance <n>` | No | Balance incluido |
| `--included-credits <n>` | No | Créditos incluidos |
| `--market-prices <json>` | Requerido para una variante | Precios por mercado como objetos `{marketGroupId, currency, price}` |
| `--metadata <json>` | No | Metadata del precio |

Creá una variante seleccionable que sólo cambie Argentina y herede el resto del precio base:

```bash theme={null}
commet plans add-price \
  --plan-id pln_xxx \
  --billing-interval monthly \
  --inherits-from-price-id pp_base \
  --market-prices '[{"marketGroupId":"pmg_argentina","currency":"ars","price":1500000}]'
```

```bash theme={null}
commet plans list                                    # Listar todos los planes
commet plans list --include-private true              # Incluir planes privados
commet plans get --id pro                            # Detalle de un plan
commet plans update --id pln_xxx --name "Pro Plus" --description "For growing teams" --metadata '{}' --is-public true  # Actualizar un plan
commet plans delete --id pln_xxx                    # Eliminar un plan
commet plans set-visibility --id pln_xxx --is-public false
commet plans update-feature --plan-id pln_xxx --feature-id ftr_xxx --included-amount 2000
commet plans remove-feature --plan-id pln_xxx --feature-id ftr_xxx
commet plans update-price --plan-id pln_xxx --price-id pp_xxx --price 3900
commet plans delete-price --plan-id pln_xxx --price-id pp_xxx
commet plans set-default-price --plan-id pln_xxx --price-id pp_xxx
```

### Precios regionales

Definí overrides en moneda local para un precio.

```bash theme={null}
commet plans set-regional-prices \
  --plan-id pln_xxx \
  --price-id pp_xxx \
  --overrides '[{"currency":"EUR","price":2700},{"currency":"BRL","price":14900}]'
```

```bash theme={null}
commet plans delete-regional-prices --plan-id pln_xxx --price-id pp_xxx
```

## Features

Gestioná el catálogo de features de la organización.

**`commet features create`**

Creá una feature.

```bash theme={null}
commet features create --code api_calls --name "API Calls" --type usage --unit-name calls
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--code <code>` | Sí | Código de la feature |
| `--name <nombre>` | Sí | Nombre de la feature |
| `--type <type>` | Sí | `boolean`, `usage`, `seats`, o `quota` |
| `--description <desc>` | No | Descripción de la feature |
| `--unit-name <nombre>` | No | Nombre de la unidad para features medidas |

```bash theme={null}
commet features list                                             # Listar el catálogo de features
commet features get --code api_calls                             # Obtener la definición de una feature
commet features update --code api_calls --name "API Requests" --description "HTTP API calls" --unit-name requests  # Actualizar una feature
commet features delete --code api_calls                          # Eliminar una feature
```

## Feature Access

Consultá el acceso y uso de features de un cliente.

```bash theme={null}
commet feature-access list --customer-id user_123                       # Listar acceso de un cliente
commet feature-access get --customer-id user_123 --code api_calls       # Detalle de acceso de una feature
```

Usá `commet usage check --customer-id user_123 --feature-code api_calls --quantity 1` para evaluar un consumo futuro.

## Seats

Gestioná asignaciones de asientos para billing por asiento.

**`commet seats add`**

Agregá asientos a un cliente.

```bash theme={null}
commet seats add --customer-id user_123 --feature-code team_member
```

```bash theme={null}
commet seats add --customer-id user_123 --feature-code team_member --count 5
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--customer-id <id>` | Sí | ID del cliente |
| `--feature-code <code>` | Sí | Código de la feature |
| `--count <n>` | No | Cantidad de asientos a agregar. Default: `1` |

```bash theme={null}
commet seats remove --customer-id user_123 --feature-code team_member
commet seats set --customer-id user_123 --feature-code team_member --count 10
commet seats set-all --customer-id user_123 --seats '{"team_member":5,"admin":2}'
commet seats get-balance --customer-id user_123 --feature-code team_member
commet seats get-all-balances --customer-id user_123
```

## Usage

Registrá eventos de consumo y verificá el margen disponible.

**`commet usage track`**

Registrá un evento de uso. Soporta tracking por valor y por tokens de modelos AI.

```bash theme={null}
commet usage track --feature-code api_calls --customer-id user_123 --value 1
```

```bash theme={null}
commet usage track \
  --feature-code gpt-4o \
  --customer-id user_123 \
  --model gpt-4o \
  --input-tokens 500 \
  --output-tokens 150 \
  --cache-read-tokens 200
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--feature-code <code>` | Sí | Código de la feature |
| `--customer-id <id>` | Sí | ID del cliente |
| `--value <n>` | Uno de `value` / `model` | Valor de uso (tracking estándar) |
| `--model <modelo>` | Uno de `value` / `model` | Nombre del modelo AI (tracking por tokens) |
| `--input-tokens <n>` | No | Tokens de entrada (tracking por tokens) |
| `--output-tokens <n>` | No | Tokens de salida (tracking por tokens) |
| `--cache-read-tokens <n>` | No | Tokens de lectura de caché (tracking por tokens) |
| `--cache-write-tokens <n>` | No | Tokens de escritura de caché (tracking por tokens) |
| `--event-id <id>` | No | ID del evento definido por quien llama para deduplicación. Máximo 200 caracteres |
| `--timestamp <ts>` | No | Timestamp del evento (ISO 8601) |
| `--properties <json>` | No | Propiedades del evento como array JSON de entradas `{ "property": string, "value": string }` |

```bash theme={null}
commet usage check --customer-id user_123 --feature-code api_calls --quantity 1
```

## Addons

Creá y gestioná extensiones de features comprables.

**`commet addons create`**

Creá un addon.

```bash theme={null}
commet addons create \
  --name "Extra Storage" \
  --base-price 500 \
  --feature-id ftr_xxx \
  --consumption-model metered
```

```bash theme={null}
commet addons create \
  --name "Priority Support" \
  --base-price 2900 \
  --feature-id ftr_xxx \
  --consumption-model boolean
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--name <nombre>` | Sí | Nombre del addon |
| `--base-price <n>` | Sí | Precio base en centavos |
| `--feature-id <id>` | Sí | ID de la feature |
| `--consumption-model <model>` | Sí | `boolean`, `metered`, `credits`, o `balance` |
| `--description <desc>` | No | Descripción del addon |
| `--included-units <n>` | No | Unidades incluidas (metered) |
| `--overage-rate <n>` | No | Tasa de excedente (metered/balance) |
| `--credit-cost <n>` | No | Costo en créditos (credits) |

```bash theme={null}
commet addons list                                   # Listar todos los addons
commet addons list --limit 25 --cursor cur_xxx       # Paginar
commet addons get --id adn_xxx                     # Detalle de un addon
commet addons update --id adn_xxx --name "Extra Storage Pro" --description "100GB extra" --base-price 900 --included-units 100 --overage-rate 10  # Actualizar un addon
commet addons delete --id adn_xxx                  # Eliminar un addon
commet addons list-active --customer-id user_123     # Addons activos de un cliente
```

## Credit Packs

Creá y gestioná paquetes de créditos para planes basados en créditos.

```bash theme={null}
commet credit-packs create --name "500 Credits" --credits 500 --price 4900
commet credit-packs list                             # Listar todos los paquetes
commet credit-packs update --id cpk_xxx --price 3900  # Actualizar un paquete
commet credit-packs delete --id cpk_xxx               # Eliminar un paquete
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--name <nombre>` | Sí (create) | Nombre del paquete |
| `--credits <n>` | Sí (create) | Cantidad de créditos |
| `--price <n>` | Sí (create) | Precio en centavos |
| `--description <desc>` | No | Descripción del paquete |
| `--is-active <bool>` | No | Si el paquete está activo |

## Plan Groups

Organizá planes en grupos para pricing tables y el portal del cliente.

```bash theme={null}
commet plan-groups create --name "Main Plans" --description "Primary pricing tiers" --is-public true
commet plan-groups list                              # Listar todos los grupos
commet plan-groups list --limit 25 --cursor cur_xxx  # Paginar
commet plan-groups get --id plg_xxx                   # Detalle de un grupo
commet plan-groups add-plan --id plg_xxx --plan-id pln_xxx --sort-order 1
commet plan-groups remove-plan --id plg_xxx --plan-id pln_xxx
commet plan-groups reorder-plans --id plg_xxx --plan-ids '["pln_a","pln_b","pln_c"]'
commet plan-groups update --id plg_xxx --name "Updated Plans" --description "New description" --is-public false
commet plan-groups delete --id plg_xxx                # Eliminar un grupo
```

## Invoices

Listá recibos, descargá PDFs y creá ajustes.

**`commet invoices create-adjustment`**

Creá un recibo de ajuste. Usá un monto negativo para créditos.

```bash theme={null}
commet invoices create-adjustment \
  --customer-id cus_xxx \
  --amount -500 \
  --description "Courtesy credit"
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--customer-id <id>` | Sí | ID del cliente |
| `--amount <n>` | Sí | Monto en centavos. Negativo para crédito |
| `--description <desc>` | No | Descripción del ajuste |
| `--metadata <json>` | No | Metadata como objeto JSON |

```bash theme={null}
commet invoices list                                     # Listar todos los recibos
commet invoices list --limit 25 --cursor cur_xxx         # Paginar
commet invoices list --subscription-id sub_xxx           # Filtrar por suscripción
commet invoices list --customer-id cus_xxx --status paid # Filtrar por cliente/estado
commet invoices get --id inv_xxx                          # Detalle de un recibo
commet invoices get-download-url --id inv_xxx             # URL firmada del PDF
commet invoices send --id inv_xxx                         # Enviar recibo por email
commet invoices update-status --id inv_xxx --status void  # Actualizar estado (paid, void)
```

## Payments

Creá payment links alojados y cobrá métodos de pago guardados. Pagos únicos, sin suscripción ni plan. Mirá [Aceptar pagos únicos](/docs/es/accept-one-time-payments) para el ciclo completo.

**`commet payments create`**

Creá un payment link alojado. El cliente abre la `url` devuelta y paga con cualquier tarjeta.

```bash theme={null}
commet payments create \
  --amount 25000 \
  --currency usd \
  --description "Annual report"
```

```bash theme={null}
commet payments create \
  --amount 25000 \
  --currency usd \
  --description "Annual report" \
  --customer-id user_123 \
  --success-url https://yourapp.com/thanks
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--amount <n>` | Sí | Monto en centavos |
| `--currency <currency>` | Sí | Código de moneda (ej. `usd`) |
| `--description <desc>` | Sí | Aparece en el link de pago, el recibo y el comprobante |
| `--customer-id <id>` | No | ID del cliente |
| `--success-url <url>` | No | URL de redirección tras el pago exitoso |
| `--metadata <json>` | No | Metadata como objeto JSON |

```bash theme={null}
commet payments charge --customer-id user_123 --amount 25000 --currency usd --description "Annual report"  # Cobrar off-session un método de pago guardado
commet payments get --id pay_xxx                          # Detalle de un pago
commet payments list --customer-id user_123 --limit 20    # Listar pagos
commet payments cancel --id pay_xxx                       # Cancelar un payment link pendiente
```

## Transactions

Listá transacciones, procesá reembolsos y reintentá pagos fallidos.

```bash theme={null}
commet transactions list                                  # Listar todas las transacciones
commet transactions list --limit 20 --cursor cur_xxx     # Paginar
commet transactions list --status succeeded              # Filtrar por estado
commet transactions list --customer-email user@acme.com  # Filtrar por email del cliente
commet transactions get --id txn_xxx                      # Detalle de una transacción
commet transactions refund --id txn_xxx                   # Reembolso completo
commet transactions retry --id txn_xxx                    # Reintentar un pago fallido
```

## Offers

Creá Offers reutilizables de forma independiente de los planes y canales de distribución.

```bash theme={null}
commet offers create \
  --name "14 días gratis y luego 25% off" \
  --phases '[{"type":"free_trial","durationDays":14},{"type":"percentage","percentage":2500,"durationCycles":3}]'
```

`percentage` usa basis points, por lo que `2500` significa 25%. Los otros tipos de fase son `free_trial`, `amount_off` y `fixed_price`.

```bash theme={null}
commet offers list --active true
commet offers get --id ofr_xxx
commet offers update --id ofr_xxx --name "Launch offer" --phases '[{"type":"fixed_price","prices":[{"currency":"usd","amount":900}],"durationCycles":2}]'
commet offers delete --id ofr_xxx
```

Una Offer no contiene `purpose` ni asociaciones con precios. Vinculá una Offer compatible a un precio base desde el Dashboard para selección introductoria automática, enviá su ID directamente como `offerId` o referenciá una Offer de un solo descuento desde un Promo Code.

## Promo Codes

Creá y gestioná códigos de distribución que el customer ingresa en checkout.

**`commet promo-codes create`**

Creá un código promocional.

```bash theme={null}
commet promo-codes create \
  --code SUMMER25 \
  --offer-id ofr_summer25 \
  --max-redemptions 100
```

```bash theme={null}
commet promo-codes create \
  --code ANNUAL \
  --offer-id ofr_annual \
  --billing-interval yearly \
  --plan-ids '["pln_pro","pln_team"]' \
  --expires-at 2026-12-31
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--code <code>` | Sí | Código promocional |
| `--offer-id <id>` | Sí | ID de una Offer con exactamente una fase `percentage` o `amount_off` |
| `--billing-interval <interval>` | No | Restringir el canje a un intervalo |
| `--max-redemptions <n>` | No | Máximo de canjes |
| `--expires-at <date>` | No | Fecha de expiración (ISO 8601) |
| `--plan-ids <json>` | No | Restringir a planes específicos (JSON array) |

```bash theme={null}
commet promo-codes list                              # Listar todos los códigos
commet promo-codes list --limit 25 --cursor cur_xxx  # Paginar
commet promo-codes get --id prc_xxx                  # Detalle de un código
commet promo-codes update --id prc_xxx --active false --max-redemptions 50 --expires-at 2026-12-31 --plan-ids '["pln_pro"]'  # Actualizar
```

## Markets

Definí grupos de países reutilizables y referencialos desde `--market-prices` al crear o actualizar precios.

```bash theme={null}
commet markets create \
  --name "Argentina" \
  --country-codes '["AR"]'

commet markets list
commet markets get --id pmg_argentina
commet markets update --id pmg_argentina --name "Cono Sur" --country-codes '["AR","BO","PY","UY"]'
commet markets delete --id pmg_argentina
```

## Webhooks

Creá y probá endpoints de webhook.

**`commet webhooks create`**

Creá un endpoint de webhook.

```bash theme={null}
commet webhooks create \
  --url https://example.com/webhooks \
  --events '["subscription.activated","payment.received"]'
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--url <url>` | Sí | URL del webhook |
| `--events <json>` | Sí | Eventos a suscribir (JSON array) |
| `--description <desc>` | No | Descripción del webhook |

<Note>
  Para desarrollo local, usá [`commet listen`](#setup) en lugar de crear un endpoint de webhook.
</Note>

```bash theme={null}
commet webhooks list                                 # Listar todos los endpoints
commet webhooks list --limit 25 --cursor cur_xxx     # Paginar
commet webhooks delete --id whe_xxx                  # Eliminar endpoint
commet webhooks test --id whe_xxx                    # Enviar un evento de prueba
```

## Provisioning

Emití un claim link nuevo para una organización aprovisionada de forma headless que todavía no fue reclamada. El comando usa la API key de esa organización; no puede emitir un link después de que una persona la reclama.

```bash theme={null}
commet provisioning create-claim-link \
  --idempotency-key claim-acme-2026-08-16
```

Usá la misma idempotency key al reintentar el mismo request. Entregale la URL devuelta al owner humano previsto; no la publiques ni la guardes en source control.

## API Keys

Creá y gestioná API keys.

```bash theme={null}
commet api-keys create --name "Production" --expires-in-days 365
commet api-keys list                                 # Listar todas las API keys
commet api-keys list --limit 25 --cursor cur_xxx     # Paginar
commet api-keys delete --id key_xxx                  # Eliminar una API key
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--name <nombre>` | Sí (create) | Nombre de la API key |
| `--expires-in-days <n>` | No | Expiración en días |

## Portal

Generá una URL de portal para el autoservicio del cliente.

```bash theme={null}
commet portal get-url --customer-id user_123
commet portal get-url --email user@acme.com
```

Pasá `--customer-id` o `--email`, uno de los dos.

## Payouts

Gestioná cuentas bancarias de payout y solicitá payouts. Los comandos de payouts requieren una API key de una organización live; las keys de sandbox devuelven `payouts_not_available_in_sandbox`.

**`commet payouts request`**

Solicitá un payout del balance disponible.

```bash theme={null}
commet payouts request --amount 50000 --description "Weekly payout"
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--amount <n>` | Sí | Monto en centavos (USD, mínimo 1000) |
| `--description <desc>` | No | Descripción del payout |

**`commet payouts add-bank-account`**

Agregá una cuenta bancaria de destino a la cuenta de payouts.

```bash theme={null}
commet payouts add-bank-account \
  --account-number 000123456789 \
  --account-holder-name "Acme Inc." \
  --routing-number 110000000 \
  --account-type checking \
  --set-default true
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--account-number <number>` | Sí | Número de cuenta bancaria |
| `--account-holder-name <name>` | Sí | Nombre del titular |
| `--routing-number <number>` | No | Routing number |
| `--account-type <type>` | No | `checking` o `savings` |
| `--set-default <bool>` | No | Establecer como cuenta por defecto |

## Test Clock

Controlá el reloj de prueba de sandbox para simular el paso del tiempo.

<Warning>
  **Solo sandbox.** Los comandos de test clock fallan contra organizaciones live.
</Warning>

**`commet test-clock advance`**

Avanza el test clock y procesa cada deadline de billing vencido antes de la fecha objetivo.

```bash theme={null}
commet test-clock advance --advance-days 30
```

```bash theme={null}
commet test-clock advance --frozen-time 2026-07-01T00:00:00Z
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--advance-days <n>` | Uno de `advance-days` / `frozen-time` | Días para adelantar el reloj |
| `--frozen-time <ts>` | Uno de `advance-days` / `frozen-time` | Instante absoluto al que mover el reloj (ISO 8601) |

```bash theme={null}
commet test-clock get # Estado actual del reloj y de la última corrida
```

El comando anterior `commet test-clock process-billing` está deprecado. `advance` ahora inicia automáticamente el procesamiento de billing.

## Quota

Gestioná allowances de quota para features basadas en quota.

**`commet quota add`**

Sumá al allowance de quota de un cliente para una feature.

```bash theme={null}
commet quota add --feature-code api_calls --customer-id user_123 --count 100
```

| Flag | Requerido | Descripción |
| - | - | - |
| `--feature-code <code>` | Sí | Código de la feature |
| `--customer-id <id>` | Uno de `customer-id` / `external-id` | ID del cliente |
| `--external-id <id>` | Uno de `customer-id` / `external-id` | ID externo del cliente |
| `--count <n>` | No | Cantidad a sumar. Default: `1` |
| `--idempotency-key <key>` | No | Clave HTTP de idempotencia para deduplicar la solicitud |

```bash theme={null}
commet quota set --feature-code api_calls --customer-id user_123 --count 500    # Establecer allowance exacto
commet quota remove --feature-code api_calls --customer-id user_123 --count 10  # Restar del allowance
commet quota get --customer-id user_123 --feature-code api_calls                # Allowance de una feature
commet quota get-all --customer-id user_123                                     # Todos los allowances
```

## Opciones globales

Estos flags funcionan en cualquier comando:

| Flag | Descripción |
| - | - |
| `--output <formato>` | `human` (default) o `agent` (JSON) |
| `--help` | Mostrar ayuda de cualquier comando |
| `--version` | Mostrar versión del CLI |

Usá `--output agent` para salida JSON estructurada en scripts y pipelines de CI:

```bash theme={null}
commet customers list --output agent | jq '.[0].id'
```

## CI/CD

Configurá `COMMET_API_KEY` como variable de entorno. No necesitás `commet login`.

```yaml .github/workflows/billing.yml theme={null}
env:
  COMMET_API_KEY: ${{ secrets.COMMET_API_KEY }}
steps:
  - run: npx commet push --yes --output agent
```

```yaml .github/workflows/subscription.yml theme={null}
env:
  COMMET_API_KEY: ${{ secrets.COMMET_API_KEY }}
steps:
  - run: |
      npx commet subscriptions create \
        --customer-id user_123 \
        --plan-code pro \
        --billing-interval monthly \
        --output agent
```

## Archivos de configuración

| Archivo | Creado por | Propósito |
| - | - | - |
| `~/.commet/auth.json` | `commet login` | Credenciales de autenticación global |
| `.commet/config.json` | `commet link` | Vínculo proyecto ↔ organización y API key auto-generada |
| `commet.config.ts` | `commet pull` | Config de billing generada con tipos |

<Note>
  Ejecutá `commet <comando> --help` para la lista completa de flags y opciones en cualquier comando.
</Note>


## Related topics

- [Creá una API key](/docs/es/create-api-key.md)
- [Aceptar pagos únicos](/docs/es/accept-one-time-payments.md)
- [Portal del Cliente](/docs/es/customer-portal.md)
- [Administrar clientes](/docs/es/manage-customers.md)
- [Customer Credits](/docs/es/customer-credits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.