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

# CLI Commands

> Query traces, logs, and errors from Monocle Studio directly in your terminal

Monocle Studio exposes CLI commands to query your local telemetry data without opening the browser. Useful for quick checks, scripting, or piping data into other tools.

These commands are also great for AI coding agents. Instead of copy-pasting logs from your terminal into Claude or Codex, your agent can call `monocle studio errors` or `monocle studio traces` directly and get full context on its own.

## Dev

Start the local Studio server. This is the main entry point for Monocle Studio.

```bash theme={"theme":"vesper"}
monocle studio dev
```

| Option      | Default   | Description                           |
| ----------- | --------- | ------------------------------------- |
| `--port`    | `4200`    | Port for the Studio UI and API        |
| `--host`    | `0.0.0.0` | Host to bind to                       |
| `--open`    |           | Open browser automatically            |
| `--clean`   |           | Clear all stored data before starting |
| `--db-path` |           | Custom path for the DuckDB database   |

```bash theme={"theme":"vesper"}
monocle studio dev --port 3000 --open
monocle studio dev --clean              # Fresh start, no past data
```

## Traces

Fetch recent traces from Studio. Each trace shows the HTTP method, path, status code, duration, and service name.

```bash theme={"theme":"vesper"}
monocle studio traces
```

You can filter by service name or trace ID, and control the output format.

```bash theme={"theme":"vesper"}
monocle studio traces --service my-api --format json
monocle studio traces --trace-id abc123 --limit 10
```

## Logs

Fetch recent logs with optional severity and search filters.

```bash theme={"theme":"vesper"}
monocle studio logs
monocle studio logs --severity error
monocle studio logs --search "payment failed" --limit 100
```

## Errors

Fetch recent exceptions with type, message, and stack trace preview.

```bash theme={"theme":"vesper"}
monocle studio errors
monocle studio errors --trace-id abc123
```

## Install agent instructions

Append a managed Monocle Studio block to `AGENTS.md` or `CLAUDE.md` so your agents know about Monocle Studio and how to use it.

```bash theme={"theme":"vesper"}
monocle studio install-agents
```

The command prompts for the target file, appends the block at the end, and updates only that managed block on later runs.

## Output formats

The `traces`, `logs`, and `errors` commands support three output formats via the `--format` flag.

| Format   | Description                                          |
| -------- | ---------------------------------------------------- |
| `pretty` | Human-readable with colors and indentation (default) |
| `short`  | One line per entry, compact                          |
| `json`   | Raw JSON, useful for piping to `jq` or other tools   |

```bash theme={"theme":"vesper"}
monocle studio traces --format short
monocle studio logs --format json | jq '.[] | .body'
```

## Common options

The `traces`, `logs`, and `errors` commands share these options.

| Option         | Default  | Description                              |
| -------------- | -------- | ---------------------------------------- |
| `-p, --port`   | `4200`   | Studio server port                       |
| `-f, --format` | `pretty` | Output format: `pretty`, `json`, `short` |
| `-n, --limit`  | `25`     | Number of entries to fetch               |
| `--trace-id`   |          | Filter by trace ID                       |

<Tip>
  Make sure Monocle Studio is running (`monocle studio dev`) before using the query commands. They connect to the local Studio server over HTTP.
</Tip>