Quickstart

Build your first incur CLI in 5 minutes

Overview

This tutorial walks you through creating a simple CLI that greets users. You’ll learn:

• How to create a CLI with Cli.create()
• How to define arguments and options with Zod schemas
• How to add multiple commands
• How to enable agent discovery
• How to test your CLI with an agent

1. Create a simple CLI

   Create a new file greet.ts with a basic single-command CLI:

   greet.ts

   import { Cli, z } from 'incur'
   
   const cli = Cli.create('greet', {
     description: 'A greeting CLI',
     args: z.object({
       name: z.string().describe('Name to greet'),
     }),
     run(c) {
       return { message: `hello ${c.args.name}` }
     },
   })
   
   cli.serve()
   

   Key points: Cli.create() takes a name and configuration. The args field defines positional arguments with Zod schemas. The run() function receives typed context with c.args.name, and the return value is automatically wrapped and formatted.

2. Run your CLI

   Execute your CLI:

   npx tsx greet.ts world
   

   You’ll see:

   message: hello world
   

   This is TOON format (Token-Optimized Object Notation) - more readable than JSON and uses 60% fewer tokens.

   Try adding --json to see JSON output: npx tsx greet.ts world --json

   Check the built-in help:

   npx tsx greet.ts --help
   

   Output:

   greet – A greeting CLI
   
   Usage: greet <name>
   
   Arguments:
     name  Name to greet
   
   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
   
3. Add options

   Extend your CLI with options for more control:

   greet.ts

   import { Cli, z } from 'incur'
   
   const cli = Cli.create('greet', {
     description: 'A greeting CLI',
     args: z.object({
       name: z.string().describe('Name to greet'),
     }),
     options: z.object({
       loud: z.boolean().optional().describe('Shout the greeting'),
       emoji: z.boolean().optional().describe('Add emoji'),
     }),
     run(c) {
       let message = `hello ${c.args.name}`
       if (c.options.loud) message = message.toUpperCase()
       if (c.options.emoji) message = `👋 ${message}`
       return { message }
     },
   })
   
   cli.serve()
   

   Try it:

   npx tsx greet.ts world --loud --emoji
   

   Output:

   message: 👋 HELLO WORLD
   
4. Add multiple commands

   Convert your CLI to support multiple commands:

   greet.ts

   import { Cli, z } from 'incur'
   
   const cli = Cli.create('greet', {
     version: '1.0.0',
     description: 'A greeting CLI',
   })
   
   cli.command('hello', {
     description: 'Say hello',
     args: z.object({
       name: z.string().describe('Name to greet'),
     }),
     options: z.object({
       loud: z.boolean().optional().describe('Shout the greeting'),
     }),
     run(c) {
       const message = `hello ${c.args.name}`
       return { message: c.options.loud ? message.toUpperCase() : message }
     },
   })
   
   cli.command('goodbye', {
     description: 'Say goodbye',
     args: z.object({
       name: z.string().describe('Name to say goodbye to'),
     }),
     run(c) {
       return { message: `goodbye ${c.args.name}` }
     },
   })
   
   cli.serve()
   
   export default cli
   

   Now you can:

   npx tsx greet.ts hello alice
   # → message: hello alice
   
   npx tsx greet.ts goodbye bob
   # → message: goodbye bob
   
   npx tsx greet.ts --help
   # Shows all available commands
   

   The export default cli is important for agent discovery and type generation.

5. Enable agent discovery

   Make your CLI discoverable by AI agents using Skills:

   npx tsx greet.ts skills add
   

   This generates skill files and installs them globally so agents can discover your CLI automatically.

   Output:

     ✓ greet  A greeting CLI
   
   1 skill synced
   
   Run `greet --help` to see the full command reference.
   

   Skills are lightweight Markdown files that describe your CLI’s commands, arguments, and options. They’re automatically kept in sync with your code.

   Alternatively, register as an MCP server:

   npx tsx greet.ts mcp add
   

   This adds your CLI to your agent’s MCP configuration.

6. Test with an agent

   Now your agent can discover and use your CLI. Try asking:

   Skills (OpenCode, Cursor, etc.)

   "Use the greet CLI to say hello to Alice"
   

   "Use the greet tool to say hello to Alice"
   

   The agent will automatically:

   1. Discover your CLI via Skills or MCP
   2. Read the available commands and their schemas
   3. Execute greet hello alice
   4. Parse the TOON output

   You can also test the machine-readable manifest:

   npx tsx greet.ts --llms
   

   This outputs Markdown documentation that agents can read:

   # greet hello
   
   Say hello
   
   ## Arguments
   
   | Name   | Type     | Required | Description    |
   | ------ | -------- | -------- | -------------- |
   | `name` | `string` | yes      | Name to greet  |
   
   ## Options
   
   | Flag     | Type      | Required | Description         |
   | -------- | --------- | -------- | ------------------- |
   | `--loud` | `boolean` | no       | Shout the greeting  |
   
   # greet goodbye
   
   Say goodbye
   
   ## Arguments
   
   | Name   | Type     | Required | Description              |
   | ------ | -------- | -------- | ------------------------ |
   | `name` | `string` | yes      | Name to say goodbye to   |
   

What You’ve Learned

CLI Creation

How to create CLIs with Cli.create() and add commands with .command()

Type Safety

Using Zod schemas for arguments and options with automatic type inference

Output Formats

TOON as the default token-efficient format, with JSON, YAML, and more available

Agent Discovery

Enabling automatic discovery via skills add and mcp add

Next Steps

Commands & Arguments

Deep dive into command patterns, schemas, and validation

Output & Formats

Learn about output envelopes, CTAs, and format options

Agent Integration

Configure Skills, MCP, and customize agent behavior

Complete Example

Here’s the final CLI from this tutorial:

greet.ts

import { Cli, z } from 'incur'

const cli = Cli.create('greet', {
  version: '1.0.0',
  description: 'A greeting CLI',
})

cli.command('hello', {
  description: 'Say hello',
  args: z.object({
    name: z.string().describe('Name to greet'),
  }),
  options: z.object({
    loud: z.boolean().optional().describe('Shout the greeting'),
  }),
  run(c) {
    const message = `hello ${c.args.name}`
    return { message: c.options.loud ? message.toUpperCase() : message }
  },
})

cli.command('goodbye', {
  description: 'Say goodbye',
  args: z.object({
    name: z.string().describe('Name to say goodbye to'),
  }),
  run(c) {
    return { message: `goodbye ${c.args.name}` }
  },
})

cli.serve()

export default cli

Want to see a more complete example? Check out the npm CLI example in the incur repository.