Reference
CLI Reference
Reference for Sentinel commands, subcommands, and the most important global flags.
Global flags
These flags apply across most commands. Defaults are the values Sentinel uses when nothing is configured in ~/.sentinel, the Settings page, or the CLI.
| Flag | Default | Meaning |
|---|---|---|
--db | ~/.sentinel/sentinel.db | SQLite database path |
--project | default | Project name used for scoping issues and traces |
--offline | false | Disable LLM calls and use local heuristics only |
--redact | true | Redact secrets before storing logs |
--verbose | false | Extra diagnostic output |
| `–min-level warn | error` | warn |
--batch-window | 15s | Batch duration before processing |
--dedupe-window | 60s | Duplicate suppression window for triage re-runs |
--base-url | http://localhost:11434/v1 | OpenAI-compatible LLM endpoint |
--api-key | empty | LLM API key. Prefer SENTINEL_API_KEY so the key never enters shell history. |
--model | qwen2.5-coder:7b | LLM model name |
CLI flags always win over Settings, which always win over built-in defaults. For API keys specifically, --api-key wins when it is passed explicitly; otherwise SENTINEL_API_KEY overrides the encrypted key stored by the Settings page.
OTEL and traces global flags
| Flag | Default | Meaning |
|---|---|---|
--otlp-enabled | true | Enable local OTLP receiver during ingest commands |
--otlp-http-addr | 127.0.0.1:4318 | OTLP listen address |
--otlp-correlation-lookback | 20s | Correlation window before an event |
--otlp-correlation-lookahead | 2s | Correlation window after an event |
--otlp-max-spans-per-event | 100 | Max spans returned for one event detail |
--otlp-noisy-route-patterns | /health, /ready, /live, /metrics, … | Noisy route match patterns |
--otlp-noisy-trace-sample-ratio | 0.20 | Keep ratio for noisy traces (0.0 to 1.0) |
--otlp-trace-slow-threshold-ms | 100 | Always keep traces at or above this duration |
--otlp-drop-noisy-internal-http-send-receive | true | Drop low-value internal send/receive spans for noisy routes |
--otlp-drop-low-value-internal-http-send-receive | true | Drop low-value internal send/receive spans across all routes |
The defaults are tuned so the local OTLP receiver does not balloon the database for typical web apps. Health and metrics polling routes get sampled, very short internal spans get dropped, and any trace with a span over 100ms is always kept.
Ingestion commands
sentinel docker
Auto-discover Docker containers and triage their logs.
sentinel docker
sentinel docker --all-running
sentinel docker api worker redis
Use this when your app is already running in Docker.
sentinel docker list
Show which Docker containers Sentinel would watch.
sentinel docker list
sentinel docker list --all-running
sentinel docker explain [container...]
Explain why containers are or are not being watched.
sentinel docker explain
sentinel docker explain redis
sentinel run -- <command>
Run a child process and capture both stdout and stderr.
sentinel run --offline -- npm run dev
sentinel run -- python app.py
Use run when Sentinel should launch the process itself.
sentinel stdin
Read logs from standard input.
docker logs -f api | sentinel stdin --offline
Use this when another command already produces the output you want.
sentinel watch <glob...>
Tail one or more log files continuously.
sentinel watch ./logs/*.log --offline
sentinel dev
Run or attach to a configured local dev stack using .sentinel.yml. See the full Dev guide for the config schema, init wizard, and TUI behavior.
sentinel dev
sentinel dev --group backend
sentinel dev --attach-only
sentinel dev --dry-run
sentinel dev --yes
Flags:
| Flag | Meaning |
|---|---|
--group <name> | Named service group from .sentinel.yml. Falls back to defaults.group. |
--yes | Skip the preflight confirmation prompt. |
--attach-only | Attach only to services that are already running. Skips starting command services. |
--dry-run | Print the resolved plan and exit without starting anything. |
sentinel dev also reads --project and the rest of the global flags. If --project is not set, it picks up defaults.project from .sentinel.yml; if that is unset, it uses the workspace directory name normalized to lowercase with spaces changed to dashes, falling back to dev.
sentinel dev init
Run the init wizard explicitly. Detects likely services in the workspace and writes .sentinel.yml. Errors out if the file already exists.
sentinel dev init
sentinel dev status
Show whether a sentinel dev session is active for the current workspace, and which services it brought up.
sentinel dev status
sentinel dev status --json
| Flag | Meaning |
|---|---|
--json | Print the raw runtime state as JSON for scripts. |
Exits non-zero if no session is active or the recorded supervisor PID is no longer alive (in which case the stale state file is cleaned up).
sentinel dev stop
Stop the active session from another terminal.
sentinel dev stop
sentinel dev stop --force
| Flag | Meaning |
|---|---|
--force | Send SIGKILL instead of SIGINT. Use only after a graceful stop times out (8 seconds). |
sentinel dev doctor
Check the local environment required for a group: docker, docker compose, and the first binary in each command service.
sentinel dev doctor
sentinel dev doctor --group api-only
sentinel dev doctor --json
| Flag | Meaning |
|---|---|
--group <name> | Restrict the check to one group. |
--json | Print the report as JSON for scripts. |
Dev TUI keybindings
| Key | Action |
|---|---|
j / k | Move between services |
a | Show all services combined |
s | Stop the selected service |
r / Enter | Start or restart the selected service |
c | Copy the visible log pane to the system clipboard |
PageUp / PageDown | Scroll logs |
/ | Filter visible logs |
p / f | Pause or resume follow mode |
m | Toggle the metrics strip |
o | Open the local web UI |
? | Toggle help |
q / Ctrl+C | Quit the dev TUI |
Normal terminal drag selection is preserved for visible text. When --redact is enabled (the default), secrets are redacted before logs are shown in the dev TUI or copied with c.
Issue inspection and triage
sentinel history
Show recently seen fingerprints.
sentinel history
sentinel explain <fingerprint>
Show detailed information for one fingerprint.
sentinel explain a4f1b2c
sentinel explain --last 5
sentinel analyze
Re-run triage on frequent unresolved fingerprints or recent ones.
sentinel analyze
sentinel analyze --last 10
Status commands
Use a fingerprint prefix:
sentinel investigate a4f1b2c
sentinel resolve a4f1b2c
sentinel suppress a4f1b2c
sentinel unsuppress a4f1b2c
Supported status flow:
newinvestigatingresolvedregressedsuppressed
If a resolved issue reappears after a quiet period, Sentinel can mark it regressed.
Traces and performance
sentinel traces
List recent trace rows with filters.
sentinel traces
sentinel traces --window 7d --protocol http --service api
sentinel traces --http-status 5xx --min-duration-ms 250
Important flags:
| Flag | Meaning |
|---|---|
--window | 1h, 24h, 7d, 30d, or all |
--protocol | http, grpc, db, or other |
--service | Filter by service name |
--http-status | Filter by status class such as 5xx |
--query | Free-text search in name/path/method |
--sort | end_time or duration_ms |
--order | asc or desc |
--limit, --offset | Pagination |
sentinel trace <trace-id>
Show spans for one trace.
sentinel trace <trace-id>
sentinel trace <trace-id> --attrs
Use --attrs when you want the diagnostic attrs_json payload for each span.
UI and runtime utilities
sentinel ui
Start the local web UI.
sentinel ui
sentinel ui --host 0.0.0.0 --port 4041 --open=false
UI-only flags:
| Flag | Meaning |
|---|---|
--host | Bind address |
--port | HTTP port, default 4040 |
--open | Open the browser automatically |
sentinel check
Verify LLM connectivity and model availability.
sentinel check
sentinel check --quick
--quick only checks the lightweight model listing path.
sentinel update
Update the installed binary from the public dist repo.
sentinel update
sentinel update --check
sentinel update --tag 0.1.0+8
Important flags:
| Flag | Meaning |
|---|---|
--check | Only report whether an update is available |
--force | Install even if the current version matches or is newer |
--repo | Override the release repository |
--tag | Install a specific version/tag |
--timeout | Network timeout |
sentinel version
Print version information.
sentinel version
sentinel version --short
Project commands
sentinel project list
List known projects in the local database.
sentinel project list
sentinel project delete <project>
Delete one project’s stored fingerprints, traces, sessions, and related rows.
sentinel project delete my-project --dry-run
sentinel project delete my-project --yes
Use --dry-run before destructive cleanup. Use --yes to confirm deletion without an extra prompt.
Built-in helpers
Cobra provides two helpers that are not Sentinel-specific but are part of the binary.
sentinel help [command]
Print help for the binary or any subcommand.
sentinel help
sentinel help dev
sentinel help dev doctor
Equivalent to sentinel <command> --help.
sentinel completion <shell>
Generate a shell completion script for bash, zsh, fish, or powershell.
# zsh, current session
source <(sentinel completion zsh)
# zsh, persistent
sentinel completion zsh > "${fpath[1]}/_sentinel"
# bash
sentinel completion bash > /etc/bash_completion.d/sentinel
Piping into sentinel
sentinel will read from stdin if data is being piped to it without an explicit subcommand:
docker logs -f api | sentinel --offline
This is equivalent to sentinel stdin --offline. Prefer the explicit form in scripts so the intent is obvious.