# Command line

The `arnscope` command talks to the ARNscope app that is running on your Mac. Each command runs through the same code as the app's own buttons, so a change shows in the window at once, with a notice such as "Command line: opened tunnel orders-db (staging)."

It is built for scripts and for coding agents: arguments in, one JSON result out, and clear exit codes.

## Turn it on

1. In ARNscope, open **Settings → Command line** and turn on **Allow command-line control**. It is off by default.
2. Settings then shows a one-line install command with a copy button. Run it once in Terminal:

   ```fish
   sudo ln -sf '<path shown in Settings>' /usr/local/bin/arnscope
   ```

   It links the app's own executable as `arnscope`: there is nothing else to install.
3. Try `arnscope help`.

While the setting is on, ARNscope listens on a Unix socket in its data folder that only your user account can open, and it checks that every connection comes from your user. Turning the setting off closes the socket.

If the app is not running, a command starts it in the background and waits up to 20 seconds for it.

## Usage

```
arnscope <command> <action> [arguments] [--flag value]
```

Flags take `--flag value` or `--flag=value`. Quote names with spaces. `arnscope help <command>`, `arnscope <command> --help` or `arnscope <command>` alone print the full help for that command, with every field, rule and an example.

| Command | What it does |
| --- | --- |
| `status` | Prints `{"app": "ARNscope", "version": "…"}`. Checks that the app answers. |
| `tunnel list` | Every saved tunnel. |
| `tunnel start <name\|id>` | Opens the tunnel and prints its state. |
| `tunnel stop <name\|id>` | Closes the tunnel. |
| `tunnel save --from <file\|->` | Adds a new tunnel from JSON. |
| `db list` | Every saved database connection, with its id and route. |
| `db save --from <file\|->` | Adds a new database connection from JSON. |
| `alarm pin <alarm name> --profile P --region R [--label L]` | Pins a CloudWatch alarm to the desktop widgets. |
| `alarm unpin <alarm name> --profile P --region R` | Removes that pin. |
| `dashboard import <file> --profile P [--region R] [--name N]` | Adds a CloudWatch dashboard file to **My dashboards**. |

`--from -` reads the JSON from stdin. Files and stdin are read up to 4 MB.

## Tunnels

`tunnel start` and `tunnel stop` take a tunnel's name when exactly one tunnel has it; otherwise use the `id` from `tunnel list`.

`tunnel list`, `tunnel start`, `tunnel stop` and `tunnel save` print each tunnel as:

| Field | Meaning |
| --- | --- |
| `id` | The tunnel's id. |
| `name` | Its name. |
| `state` | `connecting`, `connected`, `reconnecting`, `stale`, `signIn`, `closed` or `stopped`. |
| `attempt` | The reconnect attempt, while `reconnecting`. |
| `reason` | Why it stopped or can't start, when there is one. |
| `profile`, `region` | Where it runs. |
| `kind` | `rds`, `msk`, `valkey` or `custom`. |
| `resource` | The RDS identifier, MSK cluster ARN or cache ARN. |
| `forwards` | `[{"host": "…", "port": N}]`. |
| `instanceName` | The Name tag it follows, if any. |
| `note` | For example "Instance replaced. Now using i-… (was i-…)." |

`tunnel start` returns while the tunnel is still `connecting`. Run `tunnel list` until it is `connected`, or `signIn` when the profile needs a fresh login.

### Tunnel JSON

Fields are camelCase; unknown fields are refused.

| Field | Required | Value |
| --- | --- | --- |
| `name` | yes | 1–64 characters. |
| `profile` | yes | An AWS profile from `~/.aws` that can start SSM sessions on the instance. |
| `region` | yes | Like `us-east-1`. |
| `instanceId` | yes | `i-…`: an SSM-managed EC2 instance that can reach every forward's host. |
| `kind` | yes | `rds`, `msk`, `valkey` or `custom`. |
| `resource` | for rds, msk, valkey | rds: the RDS instance or cluster identifier. msk: the cluster ARN. valkey: the ElastiCache cache ARN. custom: leave it out. |
| `forwards` | yes | `[{"host": "…", "port": N}]`, 1–32 entries. rds and valkey take exactly one (the endpoint); msk one per broker. |
| `documentName` | no | `AWS-StartPortForwardingSessionToRemoteHost` (the default), or `AWS-StartPortForwardingSession` when every forward's host is `localhost`. |

Leave out `id`, `keepOpen`, `localAccess` and `localPort`: the command line cannot set them.

```json
{
  "name": "orders-db (staging)",
  "profile": "staging",
  "region": "us-east-1",
  "instanceId": "i-0123456789abcdef0",
  "kind": "rds",
  "resource": "orders-db",
  "forwards": [{ "host": "orders-db.abc123xyz.us-east-1.rds.amazonaws.com", "port": 5432 }]
}
```

```fish
arnscope tunnel save --from orders-tunnel.json
arnscope tunnel start "orders-db (staging)"
```

## Database connections

RDS databases (PostgreSQL, MySQL, Aurora) come from the RDS list in the app and need no saved connection. Save one only for a database outside it: self-hosted, StarRocks, ClickHouse, another account. See [MySQL, StarRocks and ClickHouse](https://arnscope.com/docs/mysql-clickhouse) for routes, TLS and sign-in.

`db list` and `db save` print each connection with every field below, plus `id`, `createdAt` and `updatedAt`.

### Connection JSON

Fields are camelCase; unknown fields, including `password`, are refused.

| Field | Required | Value |
| --- | --- | --- |
| `name` | yes | 1–100 characters. |
| `engine` | yes | `mysql`, `mariadb`, `aurora-mysql`, `starrocks` or `clickhouse`. |
| `route` | yes | `{"kind": "tunnel", "tunnelId": "<id from arnscope tunnel list>"}`, `{"kind": "local", "localPort": 13306}` (a port your own tunnel listens on) or `{"kind": "direct"}` (the host is reachable from this Mac). |
| `host`, `port` | yes | The database's own host and port. Through a tunnel: as the instance sees it. |
| `tls` | yes | `rds` (RDS certificates), `system` (public certificates) or `off`. |
| `authKind` | yes | `iam` (an RDS IAM token; not StarRocks or ClickHouse; needs TLS on), `secret` (a Secrets Manager secret) or `typed` (the user types the password in the app when connecting). |
| `profile`, `region` | for iam and secret | The AWS profile and region that sign the token or read the secret. |
| `secretArn` | for secret | `arn:aws:secretsmanager:…` |
| `secretKey` | no | The JSON field holding the password (default: `password`, `auth_token` or `token`). |
| `useSecretMetadata` | no | `true`: the secret's `host`, `port`, `username` and `dbname` win on every connect. |
| `username` | yes | The database user. |
| `database` | no | The default database. |

Rules the app enforces:

- ClickHouse cannot use an ARNscope tunnel route, IAM or `rds` TLS.
- `tls: off` is refused with IAM, and through an ARNscope tunnel unless `host` is `localhost` (or `127.0.0.1`).
- A tunnel route needs a tunnel that exists, forwards exactly `host:port`, and is in the connection's profile and region when it has one.
- A save that would need a confirmation in the app fails with "This route needs a confirmation in the app: save it there."

Example: StarRocks on an EC2 node, through a tunnel to that node itself (kind `custom`, `documentName` `AWS-StartPortForwardingSession`, forward `localhost:9030`), with the password in Secrets Manager:

```json
{
  "name": "Warehouse (staging)",
  "engine": "starrocks",
  "route": { "kind": "tunnel", "tunnelId": "<id from arnscope tunnel list>" },
  "host": "localhost",
  "port": 9030,
  "tls": "off",
  "authKind": "secret",
  "profile": "staging",
  "region": "us-east-1",
  "secretArn": "arn:aws:secretsmanager:us-east-1:111122223333:secret:starrocks-observer-AbCdEf",
  "useSecretMetadata": false,
  "username": "observer"
}
```

```fish
arnscope tunnel list
arnscope db save --from warehouse.json
```

## Alarms and dashboards

`alarm pin` and `alarm unpin` take the exact, case-sensitive alarm name. `--profile` must be a profile in `~/.aws`; `--label` is the short name the widget shows. Pinning an alarm that is already pinned prints the existing pin. The widgets hold at most 50 pins. `alarm pin` prints the pin (`id`, `kind`, `profile`, `region`, `alarmName`, `label`); `alarm unpin` prints `{"removed": "<pin id>"}`.

```fish
arnscope alarm pin "orders-api 5xx" --profile prod --region us-east-1 --label "Orders 5xx"
```

`dashboard import` adds the dashboard to **My dashboards** for that profile; nothing is created in AWS. `--region` is needed when the file names none, and `--name` overrides the file's name (a taken name becomes "Name (2)"). It prints the `id`, `name`, `profile`, `region` and any `warnings`, for example widgets that open only in the console. The file format is on the [CloudWatch dashboard files](https://arnscope.com/docs/cloudwatch-dashboards) page.

```fish
arnscope dashboard import checkout.dashboard.json --profile staging --region us-east-1
```

## Safety rules

| Rule | Why |
| --- | --- |
| Saves only add. A body with an `id` is refused: "The command line only adds new entries; leave out "id" and change existing ones in the app." | Repointing a tunnel or connection you already trust by name stays a click in the app. |
| `localAccess` and `keepOpen` are refused: "Turn on "localAccess" or "keepOpen" in the app, not from the command line." | Sharing a tunnel with other apps on this Mac, or keeping it open forever, is your choice in the app. |
| Route changes that need a confirmation are refused. | The question about another instance is asked in the app, where you see both instances. |
| No passwords. A `password` field is refused. | Use a Secrets Manager ARN, or `typed` so you type it in the app. |
| Every AWS command names its profile. | There is no default profile; `--profile` (or `profile` in the JSON) is always explicit. |
| Every change shows a notice in the app. | Nothing the command line does goes unnoticed. |

There are no delete or edit commands.

## Exit codes and errors

Results are JSON on stdout. Errors go to stderr as `arnscope: <message>`.

| Code | Meaning |
| --- | --- |
| 0 | Success (help included). |
| 1 | The app refused the command. The message says why. |
| 2 | The command could not be sent: command-line control is off, the app did not open within 20 seconds, the arguments or `--from` file are invalid, or no answer came back. |

Messages you may see:

| Message | What to do |
| --- | --- |
| Command-line control is off. Turn it on in ARNscope: Settings → Command line. | Turn on **Allow command-line control**. |
| ARNscope isn't accepting commands. Open it and turn on Settings → Command line → Allow command-line control. | Open the app and check the setting. |
| `` `tunnel` needs an action. Run `arnscope help tunnel`. `` | Add the action word. |
| --profile needs a value. / --profile is required. | Pass the flag with a value. |
| No AWS profile named “…”. Profiles: … | Use one of the listed profiles. |
| “…” is not an AWS region (like us-east-1). | Fix `--region`. |
| Give exactly one tunnel name or id (quote it if it has spaces). | Quote the name. |
| N tunnels are named “…”; use its id (arnscope tunnel list). | Use the id. |
| No saved tunnel named “…”. See arnscope tunnel list. | Check the name. |
| Pass the JSON with --from <file.json> (or --from - for stdin). | Add `--from`. |
| … is not valid JSON: … | Fix the file. |
| The widgets already hold 50 pins; unpin one first. | Unpin one. |
| … is not pinned in … …. | Check the name, profile and region. |
| This file names no region; pass --region. | Add `--region`. |
| ARNscope did not answer in time. | The app took more than 3 minutes; check the window. |
| Unknown command “…”. Run arnscope help. | Check the action word. |

Errors from the app itself (for example a tunnel or connection rule) are passed on as they are; the [SSM tunnels](https://arnscope.com/docs/ssm-tunnels) and [MySQL, StarRocks and ClickHouse](https://arnscope.com/docs/mysql-clickhouse) pages list them.

## Using it from an AI agent

The command line is made for agents such as Claude Code. A good routine:

1. Run `arnscope status`. Exit code 2 means the app is closed or **Allow command-line control** is off: ask the user to turn it on.
2. Run `arnscope help <command>` before using a command. It lists every field, rule and an example.
3. Run a `list` command (`tunnel list`, `db list`) to see what already exists before adding anything.
4. Name the profile every time (`--profile`, or `profile` in the JSON).
5. Write JSON to a file, or pipe it with `--from -`, and check the exit code. On 1, read the message and fix the input; do not retry blindly.
6. After `tunnel start`, poll `tunnel list` until `state` is `connected`. On `signIn`, ask the user to sign in to the profile.
7. Leave passwords, `localAccess`, `keepOpen`, edits and deletes to the user in the app.

A line like this in your project's agent instructions is enough:

```
ARNscope: run `arnscope status`, then `arnscope help <command>`. Saves only add; never pass passwords.
```

## Limitations

- macOS only, and only while the app is running (a command opens it if it is closed).
- Saves only add: there are no commands to edit or delete tunnels and connections, or to change a tunnel's local port, Keep open or followed Name tag. Do that in the app.
- There are no commands for queries, S3, logs or other pages.
- A first word that is not a command opens the app instead of running a command.

Want a command added? Write to [hello@arnscope.com](mailto:hello@arnscope.com).

Source: https://arnscope.com/docs/cli
