> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Global CLI flags for all commands

> Control Extension.js CLI behavior across all commands with global flags for telemetry opt-out, machine-readable JSON output, and verbose logging.

Use global flags to control CLI behavior consistently across commands, especially for telemetry and machine-readable output.

Extension.js telemetry is intentionally anonymous and privacy-safe. It sends at most two event types (`command_executed` and `command_failed`). Each event carries `command`, `success`, and `version`, and `create` runs add `template` and `source`. Coarse environment facts ride along (`os`, `arch`, `node_major`, `is_ci`, `is_source_build`).

## Global flag capabilities

| Capability | What it gives you |
| - | - |
| Telemetry control | Disable telemetry per-run, per-environment, or persistently |
| AI/help formatting | Return help output in readable or structured formats |
| Cross-command consistency | Apply the same control flags to `create`, `dev`, `start`, `preview`, and `build` |

## Global options

| Flag | Description | Default |
| - | - | - |
| `--version` | Print the CLI version and exit. | n/a |
| `--no-telemetry` | Disable anonymous telemetry for a single command execution. | telemetry enabled |
| `--no-browser` | Stop the browser from launching. Applies to `dev`, `start`, and `preview`. Sets `EXTENSION_CLI_NO_BROWSER=1`. | browser enabled |
| `--no-reload` | Skip the reload wrapper and dispatch so an open tab stays undisturbed. `dev` only. | reload enabled |
| `--ai-help` | Show AI-assistant oriented help output. | disabled |
| `--output <pretty\|json>` | Result format. With `--ai-help`, choose the help payload format. | `pretty` |
| `--debug` | Print maintainer diagnostics alongside normal output. On `dev`, `start`, `preview`, and `build`. | disabled |

`--format` is a deprecated alias for `--output`. It still works, and the CLI prints a deprecation warning on stderr once per run. The same applies to the older `--wait-format` alias.

Flag misuse fails with a stable code: `--no-reload` outside `dev` and `--no-browser` outside `dev`/`start`/`preview` fail with `E_FLAG_NOT_SUPPORTED_HERE`. The removed `--no-runner` flag fails with `E_REMOVED_FLAG`, use `--no-browser` instead.

You can also set no-browser mode per command in `extension.config.js` with `commands.<command>.noBrowser: true`. The CLI flag wins when both are present.

`--no-browser` is the flag that stops the browser from launching. Do not confuse it with `--no-open`, which `dev`, `start`, and `preview` each declare. Under `--no-open` the browser still launches and loads your extension. Only the tab Extension.js would open for it is skipped. Full comparison on the [dev page](/docs/commands/dev#stop-the-browser-from-launching).

## Optional boolean flags

Flags documented as `[boolean]` (for example, `--polyfill`, `--zip`, `--zip-source`, `--silent`, `--wait`, `--install`) accept an explicit value, so you can enable or disable them without a separate `--no-*` flag:

* A bare flag enables it: `extension dev --polyfill`
* `false`, `0`, `no`, and `off` disable it: `extension dev --polyfill false`
* `true`, `1`, and `yes` enable it: `extension build --zip true`

This is useful for overriding a default set in `extension.config.*` from the command line, or for passing a computed value in a script (`extension build --zip "$SHOULD_ZIP"`).

## Telemetry opt-out options

You can disable telemetry in three ways (listed in precedence order):

```bash theme={null}
# 1. Environment variable (wins over everything else)
EXTENSION_TELEMETRY_DISABLED=1 extension dev
EXTENSION_TELEMETRY=0 extension dev            # back-compat

# 2. Per-run flag
extension build --browser=chrome,firefox --no-telemetry

# 3. Persistent consent command
extension telemetry disable
```

Set `EXTENSION_TELEMETRY_DISABLED=1` in continuous integration (CI) when policy requires no telemetry across all runs.

## Practical examples

### Disable telemetry for a CI build

```bash theme={null}
EXTENSION_TELEMETRY_DISABLED=1 extension build --browser=chrome,firefox
```

Use this when policy requires explicitly disabling telemetry for automation runs.

### Generate machine-readable help for tooling

```bash theme={null}
extension dev --ai-help --output json
```

Use this for AI tooling, wrappers, or scripts that parse command help output.

### Keep readable help output for local debugging

```bash theme={null}
extension dev --ai-help --output pretty
```

Use pretty mode when you want assistant-friendly output that still reads well in terminal sessions.

## Behavior notes

* The CLI parses global flags before command-specific options.
* See `docs/TELEMETRY.md` in the Extension.js repository and [Telemetry and privacy](/docs/features/telemetry-and-privacy) for telemetry behavior and privacy details.
* Use `extension telemetry status` to check the current consent state.
* Command pages document command-specific flags separately.
* You can combine global flags with command-specific options.
* Automated tools (AI assistants and CI scripts) should read command readiness from `dist/extension-js/<browser>/ready.json`, not from terminal log parsing. See [ready.json](/docs/contracts/ready-json).

## Next steps

* Apply these flags in [create](/docs/commands/create) and [dev](/docs/commands/dev) workflows.
* Use them for production checks in [start](/docs/commands/start), [preview](/docs/commands/preview), and [build](/docs/commands/build).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.