Profiles and scoping

Nearly every command needs to know two things: which workspace, and which app. Getting this wrong is the single most common way to run a correct command against the wrong brand.

Resolution order

The CLI checks three places, first match wins:

1. The flag. --workspace or --app on the command itself.
2. The environment. OMAZY_WORKSPACE and OMAZY_APP.
3. What you pinned. Whatever omazy workspace use last set.

Flags beat environment, environment beats the pin. Explicit beats ambient, which is the order you would want if you thought about it, and the order you would regret if it were reversed.

Pinning

omazy workspace use acme

Comfortable for a day of work in one place. The failure mode is that it is invisible: a pin set on Monday is still in force on Thursday, and nothing on screen reminds you. If a command touches production, pass the flag explicitly and let the extra typing buy you certainty.

Profiles

Profiles keep separate credentials and pins side by side:

omazy --profile staging agent list

One profile per environment is the pattern that survives contact with reality. Name them after the environment rather than after yourself, because --profile imran tells the next person nothing.

Output formats

omazy agent list --output json

Format	For
table	Reading. The default.
json	Piping into jq or a script.
yaml	Reading a large object without going cross-eyed.
quiet	Ids only, for shell loops.

Use json in scripts, always. The table format exists to be read by people, and its column widths and headings are allowed to change in a way that would break anything parsing them. quiet is the one to reach for when you want to feed ids into another command.

Debugging

omazy --debug agent list

--debug shows the requests being made and the responses coming back. It is the fastest way to find out that you are pointed at a different app than you thought, which is the answer roughly half the time.