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:

$ 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

$ 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:

$ my-cli --version
1.0.0

Set the version when creating the CLI:

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:

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:

$ 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

$ my-cli status --json
{
  "clean": true
}

Equivalent to --format json.

Verbose Flag

Include the full output envelope:

$ 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

$ my-cli status --verbose --json

Output

{
  "ok": true,
  "data": {
    "clean": true
  },
  "meta": {
    "command": "status",
    "duration": 12
  }
}

LLMs Flag

Output a machine-readable manifest of all commands:

$ 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

$ my-cli --llms json

Output

{
  "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:

$ 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:

// 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:

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:

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()

$ my-cli status
{
  "clean": true
}

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

Combining Flags

Global options can be combined:

$ 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:

# 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:

$ 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
• Shell Completions

Global options are automatically available on every command. No configuration or code needed.