Read-only by default

An AWS console you cannot accidentally break

Most AWS tooling can change your infrastructure with the same keystroke that reads it. orbit separates the two. A plain orbit invocation lists, filters and describes everything in your account and writes nothing at all. You have to pass --write before a single mutating action becomes reachable.

Install orbit brew install doughlass/homebrew-tap/orbit

Why read-only is the default

The AWS console is designed to make destructive actions easy to reach. A red button for terminate sits near the instance you were reading about, one misclick away, and the confirmation dialog is the only thing standing between a typo and a terminated production host. That is a reasonable trade-off for a tool people use to make changes. It is a poor trade-off for a tool people use to look.

Most of the time you open a cloud console, you are answering a question. Which instance is holding that port. Why did the deploy fail. What is this security group attached to. Is that instance stopped and still billing me. The console makes all of those questions answerable and all of the destructive actions equally reachable.

orbit inverts that. Reading is the whole point, so reading is what you get. The write path exists, and it is useful, but it is opt-in per invocation and therefore impossible to trigger by accident during an incident at 2am when you are trying to work out why the checkout flow is down.

What you can do without --write

Read-only constrains what orbit does to your account, not what it can read. All 160+ resource views across 60+ services are browsable in the default mode, because every one of them is a read operation against the AWS API.

/ Filter anything. Client-side fuzzy matching across any resource list, or server-side AWS tag filters where the service supports them.
d Describe any resource. Full API detail for the selected item, including tags, networking, storage and IAM attachments.
s Read a secret. In Secrets Manager, s fetches the value as a read and auto-hides after 10 seconds, so a revealed value cannot idle on screen.
←→ Sort and page through large collections, with ] and [ for pagination on lists that need it.
: Switch profile and region at runtime with :profiles and :regions, without restarting.
0–5 Jump between regions from the number keys, for comparing the same resource type across regions.

What --write unlocks

With --write, orbit exposes the mutating actions: starting, stopping, rebooting and terminating EC2 instances, rotating or deleting a secret, deleting a volume, snapshot or AMI, and opening an SSM shell on an instance. Resource-specific actions are listed in the help screen with ?.

Two things stay available without the flag. Reading a Secrets Manager value is a read, not a mutation, so it works in read-only mode — and it auto-hides after ten seconds so a revealed secret cannot idle on screen. Downloading an S3 object writes to your machine, not to AWS, so it is not a write operation against your account.

The important property is that this is a per-invocation flag, not a stored preference. A write-enabled run does not change your configuration, so the next plain orbit is read-only again. You cannot accidentally leave yourself in a writable state.

orbit                    # read-only. cannot change anything.
orbit --write             # writes enabled for this run only

You still control it with IAM

orbit's read-only default is a usability property, not a security boundary. It stops you from changing things by accident; it does not stop a caller whose IAM policy already grants write permissions.

If you want a genuine guarantee that a session cannot mutate anything, pair orbit with a read-only IAM policy. Grant ec2:Describe*, s3:List* and the equivalent for the services you care about, and deny the mutating actions. orbit runs under whatever credentials the standard AWS chain resolves, so a read-only profile gives you a session that the API itself will refuse to change, regardless of which flags you pass.

That combination is the strongest posture: an IAM policy that cannot write, pointed at by a profile you select with --profile. orbit is a good tool for pointing at an account, and IAM is what makes the pointing safe. For how to wire up profiles and assumed roles, see SSO and multiple profiles.

Read-only questions

What does read-only by default mean in orbit?

orbit will not perform any mutating operation, such as stopping or terminating an EC2 instance, unless you start it with the --write flag. The default invocation can list, filter, describe and inspect resources across your account but cannot change them. Reading a Secrets Manager value is a read, so it works without the flag and auto-hides after 10 seconds.

Is it safe to point orbit at a production AWS account?

Yes, for inspecting. Because read-only is the default, a plain orbit invocation cannot modify anything in production, which makes it appropriate for browsing during an incident when you want to see the state of your account without any risk of changing it.

What happens when I pass --write?

Enabling writes applies only to that invocation, it is not a persistent setting. Mutating actions such as starting, stopping, rebooting or terminating an EC2 instance, connecting over SSM, rotating or deleting a secret, or deleting a volume, snapshot or AMI become available. Omitting --write on the next run returns the tool to read-only, so the safe default cannot be lost by accident.

What can orbit do without the --write flag?

Everything observational: browsing and filtering resource lists across 60+ AWS services, describing any resource, viewing JSON, sorting and paging through large result sets, switching profiles and regions, and revealing tags and resource relationships. These are all read operations against the AWS API.

Does read-only mode limit which AWS services I can browse?

No. Read-only is a constraint on what orbit does to your account, not on what it can read. All 160+ resource views across 60+ services are browsable without the --write flag, including EC2, S3, Lambda, RDS, IAM, EKS, ECS, CloudFormation, Route 53 and the rest.