> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wevm/incur/llms.txt
> Use this file to discover all available pages before exploring further.

# Global Options

> Built-in flags available on every incur CLI

Every incur CLI includes these flags automatically. No configuration needed.

## Built-in Flags

| Flag             | Short | Description                                          |
| ---------------- | ----- | ---------------------------------------------------- |
| `--help`         | `-h`  | Show help for the CLI or a specific command          |
| `--version`      |       | Print CLI version                                    |
| `--llms`         |       | Output agent-readable command manifest               |
| `--mcp`          |       | Start as an MCP stdio server                         |
| `--json`         |       | Shorthand for `--format json`                        |
| `--format <fmt>` |       | Output format: `toon`, `json`, `yaml`, `md`, `jsonl` |
| `--verbose`      |       | Include full envelope (`ok`, `data`, `meta`)         |

## Help Flag

Show usage information:

```sh theme={null}
$ my-cli --help
```

**Output**

```
my-cli – My CLI

Usage: my-cli <command>

Commands:
  install  Install a package
  status   Show repo status

Built-in Commands:
  completions  Generate shell completion script
  mcp add      Register as an MCP server
  skills add   Sync skill files to your agent

Global Options:
  --format <toon|json|yaml|md|jsonl>  Output format
  --help                              Show help
  --llms                              Print LLM-readable manifest
  --mcp                               Start as MCP stdio server
  --verbose                           Show full output envelope
  --version                           Show version
```

### Command-Specific Help

```sh theme={null}
$ my-cli install --help
```

**Output**

```
my-cli install – Install a package

Usage: my-cli install [package]

Arguments:
  package  Package name

Options:
  --saveDev, -D  Save as dev dependency

Global Options:
  --format <toon|json|yaml|md|jsonl>  Output format
  --help                              Show help
  --json                              Output JSON
  --verbose                           Show full output envelope
```

## Version Flag

Print the CLI version:

```sh theme={null}
$ my-cli --version
1.0.0
```

Set the version when creating the CLI:

```ts theme={null}
import { Cli } from 'incur'

Cli.create('my-cli', {
  description: 'My CLI',
  version: '1.0.0',
})
  .command('status', {
    run() {
      return { clean: true }
    },
  })
  .serve()
```

Or read from `package.json`:

```ts theme={null}
import { Cli } from 'incur'
import pkg from './package.json'

Cli.create('my-cli', {
  description: 'My CLI',
  version: pkg.version,
})
  .serve()
```

## Format Flag

Change the output format:

```sh theme={null}
$ my-cli status --format json
{
  "clean": true
}

$ my-cli status --format yaml
clean: true

$ my-cli status --format md
| Key   | Value |
|-------|-------|
| clean | true  |
```

Supported formats:

* `toon` – Terse Object Oriented Notation (default)
* `json` – Standard JSON with 2-space indentation
* `yaml` – YAML format
* `md` – Markdown tables
* `jsonl` – JSON Lines (for streaming)

### JSON Shorthand

```sh theme={null}
$ my-cli status --json
{
  "clean": true
}
```

Equivalent to `--format json`.

## Verbose Flag

Include the full output envelope:

```sh theme={null}
$ my-cli status --verbose
```

**Output**

```
ok: true
data:
  clean: true
meta:
  command: status
  duration: 12
```

The envelope includes:

* `ok` – Success indicator
* `data` – Command output
* `meta` – Metadata (command name, duration, CTAs)

In non-verbose mode, only `data` is shown.

### Verbose + JSON

```sh theme={null}
$ my-cli status --verbose --json
```

**Output**

```json theme={null}
{
  "ok": true,
  "data": {
    "clean": true
  },
  "meta": {
    "command": "status",
    "duration": 12
  }
}
```

## LLMs Flag

Output a machine-readable manifest of all commands:

```sh theme={null}
$ my-cli --llms
```

**Output (Markdown)**

```
# my-cli

## install

Install a package

**Usage:** `my-cli install [package]`

**Arguments:**
- `package` (string, optional) – Package name

**Options:**
- `--saveDev` (boolean) – Save as dev dependency
```

### JSON Schema Format

```sh theme={null}
$ my-cli --llms json
```

**Output**

```json theme={null}
{
  "tools": [
    {
      "name": "install",
      "description": "Install a package",
      "inputSchema": {
        "type": "object",
        "properties": {
          "package": {
            "type": "string",
            "description": "Package name"
          },
          "saveDev": {
            "type": "boolean",
            "description": "Save as dev dependency"
          }
        }
      }
    }
  ]
}
```

Useful for:

* Direct inspection
* Custom integrations
* Documentation generation
* Tool definition export

## MCP Flag

Start the CLI as an MCP stdio server:

```sh theme={null}
$ my-cli --mcp
```

This exposes all commands as MCP tools. The server reads JSON-RPC from stdin and writes responses to stdout.

Agents use this mode when invoking the CLI via MCP:

```json theme={null}
// Agent config (e.g., ~/.claude.json)
{
  "mcpServers": {
    "my-cli": {
      "command": "npx",
      "args": ["my-cli", "--mcp"]
    }
  }
}
```

## Implementation

All global options are handled automatically in `src/Cli.ts`. No additional code needed:

```ts theme={null}
import { Cli, z } from 'incur'

Cli.create('my-cli', {
  description: 'My CLI',
  version: '1.0.0',
})
  .command('status', {
    description: 'Show repo status',
    run() {
      return { clean: true }
    },
  })
  .serve()
```

This CLI automatically supports:

* `my-cli --help`
* `my-cli --version`
* `my-cli status --json`
* `my-cli status --verbose`
* `my-cli --llms`
* `my-cli --mcp`

## Custom Default Format

Override the default format:

```ts theme={null}
import { Cli } from 'incur'

Cli.create('my-cli', {
  description: 'My CLI',
  format: 'json', // Default to JSON instead of TOON
})
  .command('status', {
    run() {
      return { clean: true }
    },
  })
  .serve()
```

```sh theme={null}
$ my-cli status
{
  "clean": true
}
```

Users can still override with `--format toon` or other formats.

## Combining Flags

Global options can be combined:

```sh theme={null}
$ my-cli status --verbose --json
{
  "ok": true,
  "data": { "clean": true },
  "meta": { "command": "status", "duration": 8 }
}

$ my-cli install express --saveDev --json
{
  "added": 1,
  "packages": 451
}

$ my-cli --help --json
# Still shows help (--help takes precedence)
```

## Order Independence

Global options work anywhere in the command line:

```sh theme={null}
# All equivalent
$ my-cli status --json
$ my-cli --json status
$ my-cli status --format json
$ my-cli --format json status
```

## Built-in Commands

Every CLI also includes these built-in commands:

```sh theme={null}
$ my-cli completions bash   # Generate bash completions
$ my-cli mcp add            # Register as MCP server
$ my-cli skills add         # Sync skill files
```

These are covered in detail in:

* [Agent Discovery](/features/agent-discovery)
* [Shell Completions](/features/shell-completions)

<Tip>Global options are automatically available on every command. No configuration or code needed.</Tip>