ARNscopeDocs

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

  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:

    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.

{
  "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:

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:

  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

Want a command added? Write to [email protected].