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

# Command reference

> Every command, subcommand, and option of the MoleSignal CLI, with its environment variables and exit codes.

`molesignal <command> --help` prints the same for one command.

## Options of every command

Every command that talks to MoleSignal takes these:

| Option | Meaning |
| - | - |
| `--profile <name>` | The saved sign-in to use. See [Keep several sign-ins](https://docs.molesignal.com/en-US/cli/sign-in.md#keep-several-sign-ins). |
| `--url <address>` | The MoleSignal address, instead of the profile's. |
| `--token <token>` | An API token for this command only. |

A time takes an ISO time, a date and time such as `2026-10-26 14:00` in local time, a number of
seconds, milliseconds, or microseconds since the epoch, or a duration back from now. A duration
is a number and a unit: `ms`, `s`, `m`, `h`, `d`, or `w`.

## Sign-in

| Command | Options | Description |
| - | - | - |
| `login` | `--url <address>`, `--profile <name>`, `--with-token` | Signs in, in the browser or with an API token from standard input. The profile becomes the current one. |
| `logout` | `--profile <name>` | Forgets the sign-in of a profile and keeps its address. |
| `profiles` | `--json` | Lists the profiles. `profiles remove <name>` forgets one. |
| `use <profile>` | none | Makes a profile the current one. |
| `status` | none | Reports the address, profile, server, MCP protocol revision, kind of sign-in, and number of tools. |
| `whoami` | `--json` | Reports the user, organization, role, and permissions. |
| `doctor` | none | Checks Node.js, the configuration, the address, the proxy, the network and TLS, the clock, the sign-in, and the MCP endpoint. |

## Logs and queries

| Command | Options | Description |
| - | - | - |
| `streams` | `--type <type>`, `--names`, `--json` | Lists the streams of a kind, `logs` by default. |
| `logs <stream>` | `-f`, `-n`, `-q`, `--where`, `--since`, `--from`, `--to`, `--fields`, `--around`, `-B`, `-A`, `--interval`, `--json`, `--utc`, `--web` | Prints the newest logs of a stream; `-f` follows new ones. See [Read and follow logs](https://docs.molesignal.com/en-US/cli/logs.md). |
| `query "<SQL>"` | `--stream`, `--since`, `--from`, `--to`, `-n`, `--csv`, `--json`, `--utc`, `--web` | Runs one read-only SQL statement against a log stream. |
| `fields <stream> [field]` | `--type`, `--since`, `--from`, `--to`, `-n`, `--match`, `--json` | Lists the fields of a stream, or the most common values of one field. |

### `logs` options

| Option | Default | Meaning |
| - | - | - |
| `-f`, `--follow` | off | Keeps printing new logs until **Ctrl+C**. |
| `-n`, `--lines <count>` | `100` | How many of the newest logs to print first, `1` to `5000`. |
| `-q`, `--query <query>` | none | A field query, as the **Logs** page takes it. |
| `--where <condition>` | none | An SQL condition on the fields of the stream. |
| `--since <duration>` | `15m` | How far back to look. |
| `--from <time>`, `--to <time>` | none | A window instead of `--since`. `--to` does not go with `-f`. |
| `--fields <a,b,c>` | all | Prints the time and only these fields. |
| `--around <time>` | none | Prints the logs just before and after a moment. |
| `-B`, `--before <count>` | `10` | With `--around`: how many logs before it, at most `250`. |
| `-A`, `--after <count>` | `10` | With `--around`: how many logs after it, at most `250`. |
| `--interval <duration>` | `2s` | How often a follow reads. |
| `--json` | off | Prints each log as one line of JSON. |
| `--utc` | off | Prints times in UTC. |
| `--web` | off | Opens the logs on the **Logs** page instead. |

## Metrics, traces, and services

| Command | Options | Description |
| - | - | - |
| `metrics query '<PromQL>'` | `--since`, `--from`, `--to`, `-n`, `--csv`, `--json` | Runs a PromQL range query; one line per series with a sparkline. |
| `metrics names [text]`, `metrics labels <metric>`, `metrics values <metric> <label>`, `metrics series <metric>` | `-n`, `--match <label=value>`, `--json` | Lists metric names, labels, label values, and series. |
| `traces` | `--service`, `--errors`, `--min-duration`, `--since`, `--from`, `--to`, `-n`, `--json` | Lists recent traces. |
| `traces show <trace>` | `--since`, `--from`, `--to`, `--json`, `--web` | Draws a trace as a waterfall. |
| `services` | `--env`, `--namespace`, `--sort`, `--since`, `--from`, `--to`, `-n`, `--json` | Lists APM services with their health. |
| `services show <service>` | `--env`, `--namespace`, `--since`, `--json`, `--web` | Sums up one service. |
| `services compare <service> <baseline> <candidate>` | `--env`, `--since`, `--fail-on-regression`, `--json` | Compares two versions. |
| `search-jobs` | `-n`, `--json` | Lists search jobs. |
| `search-jobs submit "<statement>"` | `--stream`, `--type`, `--promql`, `--step`, `--since`, `--from`, `--to`, `--limit`, `--keep`, `--wait`, change options | Submits a search job. |
| `search-jobs show <job>`, `search-jobs results <job>`, `search-jobs cancel <job>` | `-o <file>`, `--csv`, `--json`, change options | Shows a job, writes its rows, or cancels it. |

## On-call and changes

| Command | Options | Description |
| - | - | - |
| `incidents` | `--status`, `--since`, `-n`, `--json` | Lists incidents, the active ones by default. |
| `incidents show <incident>` | `--rca`, `--json`, `--web` | Prints one incident. |
| `incidents ack <incident>`, `incidents resolve <incident>` | change options | Acknowledges or resolves an incident. |
| `oncall` | `--schedule`, `--at`, `--json` | Prints who is on call. |
| `approvals` | `--all`, `-n`, `--json` | Lists approval requests that wait or are approved. |
| `approvals show <approval>`, `approvals execute <approval>` | `--json`, change options | Prints a request, or carries out an approved change. |
| `annotate "<title>"` | `--description`, `--tags`, `--dashboard`, `--stream`, `--time`, `--end`, change options | Annotates dashboards. |
| `synthetics` | `--lifecycle`, `--json` | Lists synthetic checks. |
| `synthetics results <check>` | `--since`, `-n`, `--json` | Lists a check's latest runs. |
| `synthetics run <check>` | change options | Runs a check now; with `--wait`, waits for the runs. |

The change options are these. See [How a change runs](https://docs.molesignal.com/en-US/cli/changes.md#how-a-change-runs).

| Option | Meaning |
| - | - |
| `--reason <text>` | Why, kept with the approval and in the audit log. |
| `--wait` | When the change needs approval, waits for it, then carries the change out. |
| `--timeout <duration>` | How long `--wait` waits, `30m` by default and `10m` for `synthetics run`. |
| `-y`, `--yes` | Confirms at once where MoleSignal asks to confirm a change. |

## Releases and data

These take an API token. See [CI and releases](https://docs.molesignal.com/en-US/cli/ci.md).

| Command | Options | Description |
| - | - | - |
| `deploy` | `--service`, `--version`, `--env`, `--namespace`, `--kind`, `--status`, `--commit`, `--repository`, `--pull-request`, `--author`, `--ci-url`, `--description`, `--time`, `--dry-run`, `-- <command>` | Records a deployment. |
| `source-maps upload <path>…` | `--application`, `--service`, `--release`, `--platform`, `--arch`, `--debug-id`, `--concurrency`, `--dry-run` | Uploads JavaScript source maps. |
| `symbols upload <path>…` | `--application`, `--service`, `--release`, `--platform`, `--arch`, `--debug-id`, `--concurrency`, `--dry-run` | Uploads Flutter, Android, and Apple symbols. |
| `source-maps list`, `symbols list` | `--application`, `--service`, `--release`, `--platform`, `--kind`, `--json` | Lists uploads. |
| `source-maps delete <id>`, `symbols delete <id>` | none | Deletes an upload. |
| `send <stream>` | `--field <name=value>`, `--raw`, `--batch` | Sends the lines of standard input to a log stream. |
| `run <stream> -- <command>` | `--name`, `--field <name=value>`, `--quiet` | Runs a command and sends its output and exit status to a log stream. |

## Tools and setup

| Command | Options | Description |
| - | - | - |
| `tools [words…]` | `--domain`, `--json` | Lists the tools the user may call. `tools show <tool>` prints one with its arguments. |
| `call <tool> [name=value…]` | `--input`, `--since`, `--from`, `--to`, change options | Calls a tool and prints its result as JSON. |
| `mcp` | none | Serves MoleSignal's MCP tools over stdio. |
| `mcp setup <tool>` | `--scope`, `--installed`, `--print` | Adds the server to `claude`, `cursor`, `codex`, `vscode`, or `gemini`. |
| `open [page] [id]` | `--print` | Opens a MoleSignal page in the browser. |
| `completion <shell>` | none | Prints a completion script for `bash`, `zsh`, or `fish`. |
| `--help`, `--version` | none | Prints the help or the version. |

## Environment variables

| Variable | Meaning |
| - | - |
| `MOLESIGNAL_URL` | The MoleSignal address, instead of `--url` or the saved one. |
| `MOLESIGNAL_TOKEN` | An API token, instead of the saved sign-in. |
| `MOLESIGNAL_PROFILE` | The profile, instead of the current one. |
| `MOLESIGNAL_CONFIG` | The file that keeps the profiles. Defaults to `~/.config/molesignal/config.json`. |
| `HTTPS_PROXY`, `HTTP_PROXY` | A proxy for every request. |
| `NO_PROXY` | Hosts reached without the proxy. |
| `NODE_EXTRA_CA_CERTS` | A certificate authority to trust besides the system's. |
| `NO_COLOR` | Prints without colours. |
| `FORCE_COLOR` | Prints colours when the output is not a terminal. |

Options win over environment variables, and environment variables win over the saved profile.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | The command succeeded, or a follow was stopped. |
| `1` | The command failed; the reason is on standard error. Also: a synthetic run failed with `--wait`, a version regressed with `--fail-on-regression`, logs were rejected by `send`, or a check of `doctor` failed. |
| `2` | An unknown command, option, or argument. |
| `3` | The change waits for approval and was not carried out. |

`deploy -- <command>` and `run` exit with the command's own code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.