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

# CLI reference

> Global flags, exit codes, configuration and environment.

```
heymcp — Share a local MCP server with agent clients, and watch what they do
```

| Command                                        | What it does                                                        |
| ---------------------------------------------- | ------------------------------------------------------------------- |
| [`heymcp login`](/cli/login)                   | Sign in with GitHub. Opens your browser once.                       |
| [`heymcp logout`](/cli/login#heymcp-logout)    | Forget this machine's CLI token.                                    |
| [`heymcp share`](/cli/share)                   | Open a tunnel to a local MCP server and stay attached.              |
| [`heymcp probe`](/cli/probe)                   | Run the handshake and checks against a local server. No public URL. |
| [`heymcp sessions`](/cli/sessions)             | List your recent sessions.                                          |
| [`heymcp export`](/cli/export)                 | Export a session's tool calls.                                      |
| [`heymcp whoami`](/cli/whoami)                 | Show who this CLI is signed in as.                                  |
| [`heymcp version`](/cli/whoami#heymcp-version) | Print the installed version.                                        |

## Global flags

<ParamField path="--json">
  Machine-readable output on every command. Use this when scripting.
</ParamField>

<ParamField path="--no-color">
  Never colour the output. The `NO_COLOR` environment variable does the same.
</ParamField>

## Exit codes

Every command exits meaningfully, so the CLI is scriptable and works in CI.

| Code | Meaning                                                                  |
| ---- | ------------------------------------------------------------------------ |
| `0`  | Everything worked.                                                       |
| `1`  | `probe` found warnings, and nothing worse.                               |
| `2`  | `probe` found failures, or the server was unreachable.                   |
| `3`  | The command could not run at all — bad input, not signed in, no network. |

`1` and `2` are `probe`'s verdict on your server. Other commands exit `0` on
success and `3` on failure; they don't use `1` or `2`.

The `1` / `2` split is what makes `heymcp probe` useful as a CI gate: fail the
build on `2`, and decide separately whether warnings should block.

```bash theme={null}
heymcp probe localhost:8000 || [ $? -eq 1 ]   # fail only on real breakage
```

## Configuration

The CLI stores its token at:

```
~/.config/heymcp/config.json
```

Written with mode `0600`. Set `HEYMCP_CONFIG_DIR` to move it.

The token is masked wherever it's displayed — `hm_live_••••••••••••4k2x`.

## Environment variables

Environment always wins over the config file.

<ParamField path="HEYMCP_TOKEN" type="string">
  Your CLI token. Set this in CI rather than running `heymcp login` there.
</ParamField>

<ParamField path="HEYMCP_BEARER" type="string">
  The bearer token for `heymcp share --bearer`. Keeps it out of your shell
  history.
</ParamField>

<ParamField path="NO_COLOR" type="any">
  Disables colour, like `--no-color`.
</ParamField>

<ParamField path="HEYMCP_CONFIG_DIR" type="path" default="~/.config/heymcp">
  Where the config file lives.
</ParamField>

<ParamField path="HEYMCP_APP" type="url" default="https://app.heymcp.dev">
  The control plane. Only relevant for self-hosted deployments.
</ParamField>

<ParamField path="HEYMCP_RELAY" type="url" default="wss://relay.heymcp.dev/agent">
  The relay endpoint. Only relevant for self-hosted deployments.
</ParamField>

## Specifying a target

`share` and `probe` both take a target, and both accept the same shapes:

| You type                 | It means                         |
| ------------------------ | -------------------------------- |
| `8000`                   | `http://127.0.0.1:8000`          |
| `:8000`                  | `http://127.0.0.1:8000`          |
| `localhost:8000`         | `http://localhost:8000`          |
| `myapp.test`             | `http://myapp.test`              |
| `myapp.test:8080`        | `http://myapp.test:8080`         |
| `http://127.0.0.1:3000`  | Exactly that                     |
| `https://myapp.test/api` | Exactly that, including the path |

The default path is `/mcp` unless the target carries one or you pass `--path`.

<Warning>
  **A bare hostname defaults to `http`, and is never silently upgraded.** Herd and
  Valet serve secured sites over **HTTPS**, so for those you must write the scheme
  yourself:

  ```bash theme={null}
  heymcp share https://myapp.test
  ```

  Guessing here was deliberately avoided, because a wrong guess produces a
  confusing timeout rather than a clear error.
</Warning>

Self-signed certificates on those local hosts are accepted deliberately — a
local dev certificate is not a security boundary, and refusing it would just
mean nobody could share a Herd or Valet site.