# Profiles and scoping

How the CLI decides which workspace and app a command applies to, and how to stop guessing.

Source: https://docs.omazy.ai/reference/cli/profiles/

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

```sh
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:

```sh
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

```sh
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

```sh
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.