> ## Documentation Index
> Fetch the complete documentation index at: https://www.sentrial.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install Sentrial, scaffold agent integrations, and inspect sessions from a terminal.

The Sentrial CLI ships with `@sentrial/sdk` as the `sentrial` binary. It is designed for humans and agents: local setup, scriptable inspection, and CI checks all use API-key auth instead of browser login.

## Install

From the root of an agent repo:

```bash theme={null}
npx --yes --package=@sentrial/sdk@latest sentrial install
```

This runs the published CLI without a global install. If `@sentrial/sdk` is already installed in
the project, use `npx sentrial <command>` for subsequent commands.

The bootstrap script provides the same first-run flow:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/sentrialdev/Sentrial/main/scripts/install.sh | bash
```

The installer bootstraps the CLI through npm, installs the right SDK package for the project, and writes safe example files without committing a real API key.

## Authentication

Agents should use API keys from organization settings:

```bash theme={null}
export SENTRIAL_API_KEY=sentrial_live_xxx
```

For local human use, you can save the key once:

```bash theme={null}
npx sentrial login --api-key sentrial_live_xxx
```

The CLI resolves credentials in this order:

1. `--api-key`
2. `SENTRIAL_API_KEY`
3. `~/.sentrial/config.json`

Use `--api-url` or `SENTRIAL_API_URL` for self-hosted or local API targets.

## Setup Commands

```bash theme={null}
# Install the SDK and scaffold example integration files
npx sentrial install

# Preview without changing files
npx sentrial install --dry-run

# Scaffold examples only
npx sentrial init

# Force language detection when a repo is ambiguous
npx sentrial init --language python
npx sentrial init --language typescript
```

Generated examples use placeholder API keys, so they are safe to commit as references.

## Sessions

```bash theme={null}
# List recent sessions
npx sentrial sessions list

# Filter by time, status, or local agent name
npx sentrial sessions list --last 7d --status failed --agent support

# Print JSON for scripts and agents
npx sentrial sessions list --json

# Fetch one session and its events
npx sentrial sessions get <session-id>

# Fetch a session without events
npx sentrial sessions get <session-id> --no-events
```

## Events

```bash theme={null}
# List all events for a session
npx sentrial events list <session-id>

# Filter event type
npx sentrial events list <session-id> --type tool_call

# Machine-readable output
npx sentrial events list <session-id> --json
```

## Signals And Diagnosis

```bash theme={null}
# List detected signals
npx sentrial signals list --last 30d

# Filter signal type or source
npx sentrial signals list --type negative --source heuristic

# Diagnose a failed session from its event timeline
npx sentrial diagnose <session-id>
```

## CI Gates

Use `evaluate` in scripts to fail a build when an experiment regresses:

```bash theme={null}
npx sentrial evaluate <experiment-id> --min-score 80 --max-regression 5
```

For agent automation, prefer JSON:

```bash theme={null}
npx sentrial evaluate <experiment-id> --min-score 80 --json
```

## Reserved Commands

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

```bash theme={null}
npx sentrial clusters
npx sentrial fix <session-id>
npx sentrial replay <session-id>
```