CLI

The Sentrial CLI gives humans and agents terminal access to Sentrial. Install SDKs, scaffold integrations, inspect sessions and events, diagnose failures, and run CI gates without browser login. The published CLI ships with @sentrial/sdk 0.5.0 as the sentrial binary. This page describes that release. Start with the quickstart to send a real trace with the published TypeScript or Python SDK.

Guided setup and Doctor are prepared for a future SDK release. They are not in the currently published packages; use the commands below until publication.

Prerequisites

Node.js 18+
A Sentrial API key from organization settings

Installation

npm

npm install -g @sentrial/sdk@0.5.0

Or use without installing:

npm

npx --yes --package @sentrial/sdk@0.5.0 sentrial sessions list

Set your API key:

export SENTRIAL_API_KEY="sentrial_live_xxx"

Initialize from the root of your agent repository:

sentrial install --dry-run
sentrial install

Installation creates examples; adapt and run them to send telemetry. For a complete first trace without a framework or model provider, use the quickstart. Python projects can follow that guide directly without installing Node.

Commands

install

Install the SDK and scaffold example integration files.

sentrial install
sentrial install --dry-run
sentrial install --language python

Flag	Default	Description
`--language`	auto	Force `typescript` or `python` setup
`--dry-run`	`false`	Preview install plan without writing files

Version 0.5.0 does not accept install --json. Use --dry-run to inspect installation steps.

init

Scaffold examples without installing packages.

sentrial init
sentrial init --language typescript

Flag	Default	Description
`--language`	auto	Force `typescript` or `python` setup
`--force`	`false`	Overwrite generated examples
`--json`	`false`	Print machine-readable output

Save an API key for future CLI calls.

sentrial login --api-key sentrial_live_xxx

Flag	Default	Description
`--api-key`	—	API key to save
`--api-url`	`https://api.sentrial.com`	API base URL

sessions list

List recent sessions.

sentrial sessions list
sentrial sessions list --last 7d --status failed --agent support
sentrial sessions list --json

Flag	Default	Description
`--last`	`7d`	`24h`, `3d`, `7d`, or `30d`
`--status`	—	Filter by session status
`--agent`	—	Filter by agent slug/name locally
`--limit`	`50`	Max results (or `500` when `--agent` is given without an explicit `--limit`, so the local agent filter has enough candidates)
`--json`	`false`	Print machine-readable output

sessions get

Fetch one session and its events.

sentrial sessions get <session-id>
sentrial sessions get <session-id> --no-events

Argument / Flag	Default	Description
`<session-id>`	required	Session ID
`--no-events`	`false`	Skip event timeline fetch
`--json`	`false`	Print machine-readable output

events list

List events for a session.

sentrial events list <session-id>
sentrial events list <session-id> --type tool_call
sentrial events list <session-id> --json

Argument / Flag	Default	Description
`<session-id>`	required	Session ID
`--type`	—	Filter event type
`--limit`	`100`	Max results
`--json`	`false`	Print machine-readable output

signals list

List detected signals.

sentrial signals list --last 30d
sentrial signals list --type negative --source heuristic

Flag	Default	Description
`--last`	`7d`	`24h`, `3d`, `7d`, or `30d`
`--type`	—	Filter by signal type
`--source`	—	Filter by signal source
`--json`	`false`	Print machine-readable output

diagnose

Diagnose a failed session from its event timeline.

sentrial diagnose <session-id>

Argument / Flag	Default	Description
`<session-id>`	required	Session ID
`--json`	`false`	Print machine-readable output

evaluate

Run an experiment quality gate in CI.

sentrial evaluate <experiment-id> --min-score 80 --max-regression-percent 5
sentrial evaluate <experiment-id> --min-score 80 --json

sentrial evaluate calls /api/v1/evaluate, which requires an API key carrying the metrics:read scope. Dashboard-generated keys include it; a manually-narrowed key without it fails the CI gate with a 403.

Argument / Flag	Default	Description
`<experiment-id>`	required	Experiment ID
`--min-score`	—	Minimum score required to pass
`--max-regression-percent`	—	Maximum allowed regression
`--no-fail-on-regression`	`false`	Don’t fail the gate on baseline regression (other thresholds still apply and still exit non-zero)
`--json`	`false`	Print machine-readable output

Common Workflows

Set Up A New Agent Repo

npm install -g @sentrial/sdk@0.5.0
export SENTRIAL_API_KEY="sentrial_live_xxx"
sentrial install

Debug A Failed Session

sentrial sessions list --last 7d --status failed
sentrial sessions get <session-id>
sentrial diagnose <session-id>

Inspect Tool Calls

sentrial events list <session-id> --type tool_call
sentrial events list <session-id> --type tool_call --json

Gate An Experiment In CI

sentrial evaluate <experiment-id> --min-score 80 --max-regression-percent 5

Output

Commands print readable terminal output by default. Add --json for scripts and agents:

sentrial sessions list --json
sentrial events list <session-id> --json
sentrial evaluate <experiment-id> --min-score 80 --json

Environment Variables

Variable	Required	Default	Description
`SENTRIAL_API_KEY`	Yes	—	Your Sentrial API key
`SENTRIAL_API_URL`	No	`https://api.sentrial.com`	Base URL for the Sentrial API

Reserved Commands

These commands are intentionally present but guarded until the backing APIs are public:

sentrial fix <session-id>
sentrial replay <session-id>

Getting Started

Core Concepts

SDKs

Integrations

API Reference

Prerequisites

Installation

Commands

install

init

sessions list

sessions get

events list

signals list

diagnose

evaluate

Common Workflows

Set Up A New Agent Repo

Debug A Failed Session

Inspect Tool Calls

Gate An Experiment In CI

Output

Environment Variables

Reserved Commands

​Prerequisites

​Installation

​Commands

​install

​init

​login

​sessions list

​sessions get

​events list

​signals list

​diagnose

​evaluate

​Common Workflows

​Set Up A New Agent Repo

​Debug A Failed Session

​Inspect Tool Calls

​Gate An Experiment In CI

​Output

​Environment Variables

​Reserved Commands

Prerequisites

Installation

Commands

install

init

login

sessions list

sessions get

events list

signals list

diagnose

evaluate

Common Workflows

Set Up A New Agent Repo

Debug A Failed Session

Inspect Tool Calls

Gate An Experiment In CI

Output

Environment Variables

Reserved Commands