Skip to main content
Every incur CLI includes these flags automatically. No configuration needed.

​
Built-in Flags

FlagShortDescription
--help-hShow help for the CLI or a specific command
--versionPrint CLI version
--llmsOutput agent-readable command manifest
--mcpStart as an MCP stdio server
--jsonShorthand for --format json
--format <fmt>Output format: toon, json, yaml, md, jsonl
--verboseInclude 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:
Global options are automatically available on every command. No configuration or code needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us