Skip to main content

​
CLI options

The CLI in depths.cli.cli manages a local OTLP/HTTP server (depths.cli.app:app) and your on-disk instance layout. This page explains every command, its flags, defaults, and short examples for macOS/Linux and Windows (PowerShell).
Tip: See depths <command> --help any time for built-in usage.

​
depths init

Initialize a new on-disk instance. Creates the directory layout and baseline config by instantiating depths.core.logger.DepthsLogger once.

​
Synopsis

depths init [OPTIONS]

​
Options

FlagTypeDefaultDescription
--instance-id, -IstringdefaultLogical instance id (used as folder name under --dir).
--dir, -Dpath./depths_dataRoot directory where the instance lives.

​
Examples

depths init
depths init -I prod -D ./observability

​
depths start

Start the OTLP/HTTP server (FastAPI + Uvicorn) for an instance.

​
Synopsis

depths start [OPTIONS]

​
Options

FlagTypeDefaultDescription
--instance-id, -IstringdefaultInstance to serve.
--dir, -Dpath./depths_dataRoot directory for the instance.
--host, -Hstring0.0.0.0Bind host for OTLP/HTTP.
--port, -Pint4318Bind port (OTLP/HTTP default).
--reload, -RboolfalseCode reload. Only supported with --foreground.
--foreground, -FboolfalseRun in the current terminal (not daemonized).

​
Examples

# background (daemonized)
depths start -I prod -D ./observability -H 0.0.0.0 -P 4318

# foreground with live logs
depths start -I prod -D ./observability --foreground

# hot reload (foreground only)
depths start --foreground --reload

​
depths view

Pretty-print the latest rows from a persisted OTel table (from local or S3, depending on --storage and your environment).

​
Synopsis

depths view [OPTIONS]

​
Options

FlagTypeDefaultDescription
--instance-id, -IstringdefaultInstance to read from.
--dir, -Dpath./depths_dataRoot directory for the instance.
--storage, -SenumautoSource: autolocals3.
--rows, -nint10Show latest N rows by event_ts.
--table, -tenum—One of: spans, span_events, span_links, logs, metrics_points, metrics_hist. If omitted, a picker is shown.
--select, -srepeatable—Project specific columns (repeat -s for multiple).
--date-fromYYYY-MM-DD—Start day (UTC, inclusive).
--date-toYYYY-MM-DD—End day (UTC, inclusive).

​
Examples

# latest 10 spans
depths view -t spans

# latest 50 logs with selected columns
depths view -t logs -n 50 -s trace_id -s span_id -s body

# force local or s3
depths view -t spans -S local
depths view -t spans -S s3

​
depths status

Query the running server’s /healthz and render producer/aggregator stats.

​
Synopsis

depths status [OPTIONS]

​
Options

FlagTypeDefaultDescription
--host, -Hstring127.0.0.1Server host to probe.
--port, -Pint4318Server port to probe.
--timeout, -Tfloat5.0HTTP timeout in seconds.

​
Examples

depths status
depths status -H 127.0.0.1 -P 4318 -T 5

​
depths stop

Stop a background server for an instance. Reads the pidfile written by start, sends a graceful terminate, and escalates when needed.

​
Synopsis

depths stop [OPTIONS]

​
Options

FlagTypeDefaultDescription
--instance-id, -IstringdefaultInstance to stop.
--dir, -Dpath./depths_dataRoot directory for the instance.
--force, -FboolfalseForce kill if graceful stop fails. If SIGKILL is not available on your OS, the CLI falls back to SIGTERM.

​
Examples

depths stop
depths stop -I prod -D ./observability
depths stop --force