How to Setup

If you're new to Crux or skipped the onboarding, follow this guide to complete the setup. Just three steps and you'll be ready to start analyzing Codex sessions.

Step 1 — Install the CLI

1

Install the CLI

Install the Crux CLI on the machine you want to analyze. The CLI collects Codex session data in the background.

Open a terminal and run the following command:

curl -fsSL https://raw.githubusercontent.com/Royaltyprogram/crux-cli/main/scripts/install.sh | sh

Tip: After installation, run crux --version to verify that the CLI was installed correctly.

Step 2 — Create a CLI Token

2

Create a CLI Token

Generate an authentication token from the dashboard. This token is used by the CLI to communicate with the server.

How to Create a Token

  1. Log in to the Crux dashboard.
  2. Click the Settings tab at the top.
  3. Click the Create CLI token button.
  4. Copy the generated token.

Important: The token is displayed only once when created. Make sure to copy it. Tokens expire after 30 days.

Step 3 — Run Setup

3

Connect Your Project

Run the setup command in the repository you want to analyze. Device registration, project connection, and local session upload are handled automatically.

Run this in the repository directory you want to analyze:

crux setup

You'll be prompted to enter the token you copied earlier. Paste it in and setup is complete.

Tip: If you're using a self-hosted server, specify the server address with crux setup --server https://your-server.com.

CLI Commands

Here are the key commands available after setup is complete.

Command Description
crux setup Register the device and connect the project.
crux collect Collect local Codex sessions and upload them to the server.
crux collect --watch Continuously collect sessions in the background.
crux collect --recent 30 Batch-collect sessions from the last 30 days.
crux --version Check the installed CLI version.

Dashboard Guide

The dashboard consists of four main tabs.

Reports

View analysis reports for collected Codex sessions. Reports explain whether the model correctly understood the intent and where it misinterpreted things.

Usage Analytics

Check usage statistics including daily token usage, model/provider coverage, response latency, and tool usage patterns.

Sessions

A list of raw Codex sessions collected by the CLI. These serve as input data for the analysis engine.

Settings

Manage CLI token creation, view configuration snapshots, and check recent activity logs.