# Global options

These apply globally, across every command — not only the API ones.

-   [`--output`/`-o`](#--output-o)
-   [`--schema`](#--schema)
-   [`--dry-run`](#--dry-run)
-   [`--yes`/`-y`](#--yes-y)
-   [`--timeout`](#--timeout)
-   [`--use-login`](#--use-login)
-   [`--debug`](#--debug)

## `--output`/`-o`

`--output`/`-o` (or `MAPBOX_OUTPUT`) picks the shape:

| Value | Result |
| --- | --- |
| `auto` (default) | `text` at a terminal, `json` when piped |
| `text` | Pretty-printed, readable |
| `json` | One compact document |

Errors always go to stderr and never appear in stdout. Under `json` they're one flat object: `code`, `message`, and — where there's advice — `fix`/`next_actions`/`docs`.

## `--schema`

`mapbox <command> --schema` describes a command as JSON instead of running it — its arguments, their types, and the request it would make. Needs no token.

```sh
mapbox styles get --schema          # one command
mapbox --schema                     # the whole CLI
```

## `--dry-run`

Every mutating built-in command takes `--dry-run`: it prints the request instead of sending it, validating `--data`/`--file` along the way. This does not apply to `tilesets-cli`, which proxies to a separately installed program with its own flags.

```console
$ mapbox styles delete zz-clitest-style --dry-run
Dry run — nothing was sent.
DELETE https://api.mapbox.com/styles/v1/you/zz-clitest-style?access_token=<redacted>
```

It goes after the operation name (`mapbox styles delete ID --dry-run`), not before. A read-only command refuses it.

## `--yes`/`-y`

Destructive commands ask for confirmation, and only at a terminal — a `DELETE` command, `mapbox uninstall`, and `agent-skills update`/`uninstall` when they'd change or remove a file:

```console
$ mapbox styles delete my-style
About to DELETE https://api.mapbox.com/styles/v1/me/my-style
Continue? [y/N] n
```

`--yes`/`-y`/`MAPBOX_YES=1` skips the question — for CI, or a script run at a terminal on purpose. It does not apply to `auth login`, which always needs a person.

## `--timeout`

| Request | Budget |
| --- | --- |
| A normal request (`GET`, or a `--data` body) | 60 seconds |
| A `--file` upload | 15 minutes |

`--timeout <SECONDS>` overrides either; `MAPBOX_TIMEOUT` sets it for a whole shell.

## `--use-login`

Ignores `MAPBOX_ACCESS_TOKEN` in the environment and uses the credentials stored by [`mapbox auth login`](https://docs.mapbox.com/cli/reference/authentication/#mapbox-auth-login) instead. It's the flag to reach for when a token left in a shell profile is shadowing a login for a different account. A `--token` typed on the command line still outranks it.

## `--debug`

Prints request URLs to stderr, for troubleshooting. `MAPBOX_DEBUG=1` sets the same thing for a whole shell.