# Insights

> Understand optional command reports, new people, and feedback.

The **Insights** page shows command activity, feedback, and generation results. Open the project and click **Insights** in its sidebar.

## Usage

Anonymous command analytics is **off by default** and independent of Okibi Identity. A workspace owner or admin can turn on **Collect anonymous command analytics** to rebuild the published CLI with reporting enabled. Reports work with Okibi sign-in or your service's own sign-in. Users can suppress them by setting `DO_NOT_TRACK=1`.

Changes to the published setting rebuild the exact published source and exclude unpublished repository edits. Pending changes coalesce when the final desired setting already matches that exact source and config, avoiding an unnecessary release. Completed release versions and distributed workspace/testing artifacts are preserved. To refresh generator templates too, use **Regenerate**: it emits current templates even when the spec is unchanged, then preserves and reconciles your existing adjustments. Focused message repairs stay incremental; spec-only updates change the spec without generating code.

Reports include command names, which approved flags were used, whether the command worked (with the exit code, error type, and HTTP status when it didn't), how long it took, whether agent mode was on when the installed runtime can tell, which commands ran together, and the CLI's version and source commit. They never include what people type (positional or arbitrary flag values), what the command prints, error text, or who ran it. Delivery is best effort and reports are unverified, so counts can be incomplete.

Agent mode is a bounded CLI setting, not proof that a person, AI, or automation ran the command. `--agent=false` still records approved flag presence while reporting known mode as off. A saved profile can enable mode without explicit flag presence. Older or unsupported runtimes leave mode unknown.

Choose **Today**, **7 days**, or **30 days** for UTC calendar-day aggregates:

| Metric | What it means |
| --- | --- |
| Observed calls | Accepted command reports. |
| Succeeded and failed | Known reported terminal outcomes. Missing outcomes remain unknown and are excluded from these counts. |
| Terminal failure rate | Failures divided by reports with a known terminal outcome. Missing outcomes are excluded. |
| Command duration | Approximate p50, p95, and p99 timings, alongside the number of timed reports. Missing timings are unknown, not zero. |

Per-command metrics, daily outcomes, and recent reports help narrow down where failures occur. Release, timing, and grouping details may be unknown for older clients. Reports become eligible for deletion after 30 days and are removed in daily batches.

### Workflows, sessions, and AI summaries

The **Workflows** section shows what people try to do, inferred from the order commands run in; it is an inference, not a record of intent. The **Sessions** section lists commands reported together.

Ephemeral groups can connect calls from a shared parent process or an explicit workflow token. Parent grouping is a heuristic; neither kind identifies a person or a conversation. Groups expire after 30 minutes idle or four hours total. Calls can be ungrouped when safe grouping is unavailable.

For an explicit workflow, use the CLI-specific environment variable shown in its generated README. For `my-cli`, create a fresh token in a POSIX shell, run your commands, then unset it:

```sh
export MY_CLI_ANALYTICS_WORKFLOW="$(my-cli --analytics-workflow-id)"
# Run your my-cli commands for this workflow.
unset MY_CLI_ANALYTICS_WORKFLOW
```

Owners and admins can request a group summary. It uses a limited command sequence, approved flag names, known effective agent mode, outcomes, timing, and public descriptions, with any omitted reports disclosed. All model-written prose is **unverified AI inference** and can make unsupported claims even with valid evidence references. Observed same-command recovery is shown separately. The goal outcome remains **unknown**, even when the last command succeeded. Summaries run only on request and may be unavailable.

### New people

**New people**, at the top of the page, counts people who first ran this CLI signed in with Okibi Identity during the picked period. Anonymous reports do not count, and days are in UTC. It shows whether or not usage reports are on.

Identity-backed user and successful-command counters, and Identity billing, remain separate from anonymous command reports. You do not need to enable Identity to collect anonymous reports.

### From the terminal

```sh
okibi clis insights my-cli
```

The terminal shows anonymous report totals, successes and failures for the current and previous six UTC calendar days, with outcome and duration sample coverage. It labels Identity users and successful-command counters separately, alongside installer fetches. JSON output includes optional safe event metadata when available. Missing timing, grouping, or outcomes stay unknown. Use the following commands to retrieve raw reports and group timelines:

```sh
okibi clis insights groups my-cli --limit 20
# All accepted reports, including ungrouped reports:
okibi clis insights events my-cli --limit 50
# Only one group, in reported sequence order:
okibi clis insights events my-cli <group> --limit 50
# Request the next page using the previous response's continueCursor:
okibi clis insights events my-cli <group> --limit 50 --cursor '<continueCursor>'
```

These commands always return JSON, including with `--agent`. Each response contains `page`, `isDone`, and an opaque `continueCursor`. Pass that cursor unchanged to the same command, workspace, and optional group until `isDone` is true. Group pages contain up to 20 groups, newest activity first; event pages contain up to 50 reports. Omit the group to read all retained reports newest-received first, including ungrouped reports. Supply a group to read its reports in ascending reported sequence order. The response includes a top-level `sessionId` only when a group was requested. There is no overall 64-report retrieval limit. The commands use your normal sign-in and selected workspace, require builder access, and do not call a model or purchase hosted enrichment. The dashboard's separately requested AI summaries retain their bounded input.

Event rows include approved flag names and available outcome, timing, release, inventory, and grouping metadata. Explicit `--agent=false` still records the flag's presence when reporting is enabled; its value is never recorded. Missing metadata stays unknown. Pages reflect live data: arriving reports can change group ordering or fill earlier sequence positions. Restart a scan when you need to include those arrivals; pagination does not promise an immutable snapshot. Raw reports follow the same retention as the dashboard.

## Feedback

People and agents send feedback with your generated CLI's own `feedback` command:

```sh title="Your user's terminal"
my-cli feedback "The list command needs a status filter"
```

Each message shows its text, the CLI version, and when it arrived. It also shows an agent ID when the sender's environment sets `AGENT_ID`. Messages are kept for 90 days.

Agents connected over the [MCP server](https://okibi.ai/docs/guides/mcp.md) can send feedback too, with the `send_feedback` tool. The read-only surface leaves it out.

Read the inbox from the terminal:

```sh
okibi clis feedback my-cli --limit 20
```

## What your users control

Your CLI sends feedback only when someone runs `feedback` or an agent calls `send_feedback`. The `feedback` command saves each message on the user's machine first, in `~/.local/share/my-cli/feedback.jsonl`, then sends it to you through Okibi.

| To | Run |
| --- | --- |
| Keep one message on this machine | `my-cli feedback --local-only "Your message"` |
| Keep every message on this machine | Set `MY_CLI_FEEDBACK_LOCAL_ONLY=true` |
| See saved messages | `my-cli feedback list` |

The variable name starts with your CLI's name in capitals, with dashes turned into underscores.

## Generation

| Tile | What it shows |
| --- | --- |
| Version | The CLI's current version. |
| Endpoints covered | How many API endpoints the CLI covers. |
| Total builds | Every build of this CLI. |
| Build success rate | The share of finished builds that succeeded. Cancelled builds are left out. |
| Avg generation time | How long a successful build takes on average. |

Under it, Recent builds lists the last five builds and their status.

## Next steps

- [Okibi Identity](https://okibi.ai/docs/guides/identity.md): Set up shared sign-in and verified Identity usage. Anonymous command reports work without it.
- [Builds and chat](https://okibi.ai/docs/guides/runs-and-chat.md): Follow a build and change the CLI from the chat.