Commands — Codex CLI Connector

Full reference for all infinium-codex CLI commands.

If infinium-codex is not on your PATH, use python -m infinium_codex_connector as a drop-in replacement for all commands below.

init

Set up the connector with an interactive wizard. Also enables the codex_hooks feature flag.

infinium-codex init

Option	Description
`--agent-id`	Agent ID (skip prompt)
`--agent-secret`	Agent secret (skip prompt)
`--base-url`	API base URL (default: `https://platform.i42m.ai/api/v1`)
`--no-interactive`	Skip all prompts, use flags only

Non-Interactive

For CI or scripting:

infinium-codex init \
  --agent-id "your-agent-id" \
  --agent-secret "your-secret" \
  --no-interactive

Re-Running Init

If you already have a configuration, the wizard offers:

Update credentials — Change agent ID or secret
Reconfigure hooks — Reinstall hooks for the current project
Change trace granularity — Per-turn, per-session, or both
Full re-setup — Start fresh
Cancel

test

Send a test trace to verify your credentials and connectivity.

infinium-codex test

Option	Description
`-v`, `--verbose`	Print the full trace payload before sending

Returns exit code 0 on success, 1 on failure.

status

Show current configuration, tracing state, and hook info.

infinium-codex status

Displays:

Tracing state — active or PAUSED
Agent ID — First 12 characters
Secret — Whether configured
API URL — Target endpoint
Granularity — per-turn / per-session / both
Config source — project or env
Pending retries — Count of failed traces (if any)
Last error — Most recent error from infinium-codex errors
Hook locations — .codex/hooks.json path

pause

Temporarily stop sending traces. Hooks stay installed but events are silently skipped.

infinium-codex pause

Alias: infinium-codex stop

resume

Resume tracing after a pause.

infinium-codex resume

Alias: infinium-codex continue

history

View locally recorded trace history.

infinium-codex history

Option	Description
`-n`, `--limit`	Number of entries to show (default: 10)
`--json`	Output raw JSON lines
`--clear`	Delete all history

Examples

# Last 25 traces
infinium-codex history -n 25

# Machine-readable output
infinium-codex history --json

# Clear history
infinium-codex history --clear

errors

View the persistent connector error log.

infinium-codex errors

Option	Description
`-n`, `--limit`	Number of entries to show (default: 20)
`--json`	Output raw JSON lines
`--clear`	Delete the error log

Errors are logged when the connector encounters network failures, malformed payloads, keyring issues, or other non-fatal problems that can’t be surfaced to stderr (since hooks run without a terminal).

retry

Resend traces that failed due to network issues.

infinium-codex retry

Option	Description
`--dry-run`	Show what would be retried without sending

Failed traces are automatically saved to a failed/ directory on send failure. Use infinium-codex status to see if any retries are pending.

update-credentials

Change your agent ID or secret.

infinium-codex update-credentials

Option	Description
`--agent-id`	New agent ID (skip prompt)
`--agent-secret`	New agent secret (skip prompt)

cleanup

Remove stale temporary session files.

infinium-codex cleanup

Option	Description
`--max-age`	Max age in seconds (default: 600)
`--session-dir`	Override session directory

start

Run the connector in HTTP server mode (alternative to command hooks). Requires the [server] extra:

pip install infinium-codex-connector[server]
infinium-codex start

Option	Description
`--host`	Bind host (default: `127.0.0.1`)
`--port`	Bind port (default: `9339`)
`--log-level`	Log level

health

Check whether the HTTP server is reachable.

infinium-codex health

Option	Description
`--host`	Server host (default: `127.0.0.1`)
`--port`	Server port (default: `9339`)

uninstall

Completely remove the connector.

infinium-codex uninstall

Option	Description
`-y`, `--yes`	Skip confirmation prompt

Removes Infinium entries from .codex/hooks.json and deletes credentials (config file + keyring secret).