Command line
Last updated 13 November 2026
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
-
In ARNscope, open Settings → Command line and turn on Allow command-line control. It is off by default.
-
Settings then shows a one-line install command with a copy button. Run it once in Terminal:
sudo ln -sf '<path shown in Settings>' /usr/local/bin/arnscopeIt links the app’s own executable as
arnscope: there is nothing else to install. -
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.
{
"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 }]
}
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 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
rdsTLS. tls: offis refused with IAM, and through an ARNscope tunnel unlesshostislocalhost(or127.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:
{
"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"
}
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>"}.
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 page.
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 and MySQL, StarRocks and ClickHouse pages list them.
Using it from an AI agent
The command line is made for agents such as Claude Code. A good routine:
- 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. - Run
arnscope help <command>before using a command. It lists every field, rule and an example. - Run a
listcommand (tunnel list,db list) to see what already exists before adding anything. - Name the profile every time (
--profile, orprofilein the JSON). - 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. - After
tunnel start, polltunnel listuntilstateisconnected. OnsignIn, ask the user to sign in to the profile. - 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 [email protected].