---
title: "Record a CLI command event"
method: POST
path: "/api/v1/cli_events"
tags: ["cli_events"]
---

# Record a CLI command event

`POST /api/v1/cli_events`

## Request

- Base URL: `https://composal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://composal.com/api/v1/cli_events`
- Auth: HTTP bearer

Bearer-authenticated, best-effort telemetry. Identity is resolved by the server. Raw command arguments, input and output are not accepted. cli_command is emitted after execution with outcome and duration. Legacy starts are ignored; legacy completions are normalized to cli_command.

## Request body

- object
  - `event` 'cli_command' | 'cli_command_started' | 'cli_command_completed', required
  - `properties` object, required
    - `command` string, required
    - `invocation_id` string, required
    - `cli_name` 'com' | 'vex', required
    - `cli_version` string, required
    - `os` 'linux' | 'macos' | 'windows', required
    - `arch` 'x86_64' | 'aarch64', required
    - `agent_mode` boolean, required
    - `json_mode` boolean, required
    - `success` boolean: Required for cli_command and legacy completion events
    - `duration_ms` integer: Required for cli_command and legacy completion events

## Response `200`

Success

- object

## Other responses

- `202`: Accepted; command events are queued and legacy starts ignored. Does not confirm PostHog ingestion
- `400`: Invalid CLI event
- `401`: Bearer authentication required
- `403`: Forbidden
- `404`: Not found
- `413`: Event exceeds 4 KiB
- `422`: Unprocessable entity
- `429`: Rate limit exceeded
- `502`: Bad gateway

---

[API](https://skmtc.dev/composal/apis/vex-api.md) - [All operations](https://skmtc.dev/composal/apis/vex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/composal/apis/vex-api/revisions/19698ba051dc?raw)