incur

Features . Quickprompt . Install . Usage . Walkthrough . API Reference . License

incur for Go

incur is a Go framework for building agent-friendly command-line tools.

This repository is a third-party, unaffiliated Go fork of wevm/incur, the original TypeScript framework. The design, naming, and product ideas are upstream's work. This fork exists so Go programs can use the same style of CLI without depending on Node.

It was rewritten from TypeScript to Go by an LLM and is maintained as production software for real use. Upstream TypeScript behavior is ported or mapped at case level, with parity tracked in TEST_PARITY.md and TEST_PARITY_CASES.md.

If you want the original TypeScript project, use upstream: https://github.com/wevm/incur.

Features

• Agent discovery: built-in skills add, skills list, mcp add, --llms, and --llms-full so agents can discover your CLI without hand-written tool definitions.
• Session savings: skill splitting, command manifests, and TOON output keep token use low across discovery, invocation, and responses.
• Call-to-actions: return suggested next commands after a run so agents can continue without guessing.
• TOON output: token-efficient default output format, with JSON, YAML, Markdown, and JSONL alternatives.
• Well-formed I/O: JSON Schemas for positional arguments, options, environment variables, and output.
• Global options: --format, --full-output, --help, --json, --schema, token pagination, filtering, --llms, --mcp, and --version.
• HTTP gateway: mount any net/http handler behind a CLI command with curl-style flags.
• Serve CLIs as APIs: expose CLI commands as a standard http.Handler, including MCP over HTTP at /mcp.
• OpenAPI import: generate commands, args, options, and descriptions from an OpenAPI 3 spec.
• Streaming: stream strings, objects, final CTAs, and errors from channel-based command handlers.
• Middleware: composable before/after hooks with shared vars and typed-by-schema validation.
• Config files: load structured JSON option defaults from project or user config.
• Light Go API surface: incur.New(), .Command(), .Group(), .Serve(), .Handler(), and .Fetch().

Quickprompt

After you build a CLI with incur, prompt your agent with one of these.

Skills (recommended - lighter on tokens)

Run `<your-cli> skills add`, then show me how to use this CLI.

MCP

Run `<your-cli> mcp add`, then use the registered MCP tools when working with this project.

Manifest only

Run `<your-cli> --llms`, inspect the command manifest, then suggest the right command for my task.

Install

Requires Go 1.25 or newer.

go get github.com/smithersai/incur

Install the helper binary for schema/code generation:

go install github.com/smithersai/incur/cmd/incur@latest

Usage

Root-command CLI

Use WithRootCommand for CLIs that do one thing.

package main

import (
	"os"

	"github.com/smithersai/incur"
)

func main() {
	cli := incur.New("greet",
		incur.WithDescription("A greeting CLI"),
		incur.WithRootCommand(&incur.CommandDef{
			Description: "Greet someone",
			ArgsSchema: &incur.JSONSchema{
				Type: "object",
				Properties: map[string]*incur.JSONSchema{
					"name": {Type: "string", Description: "Name to greet"},
				},
				Required: []string{"name"},
				XOrder:   []string{"name"},
			},
			Handler: func(ctx *incur.CommandContext) (any, error) {
				return map[string]any{"message": "hello " + ctx.Args["name"].(string)}, nil
			},
		}),
	)

	if err := cli.Serve(os.Args[1:]); err != nil {
		os.Exit(1)
	}
}

$ greet world
# message: hello world

Multi-command CLI

Register subcommands with Command.

package main

import (
	"os"

	"github.com/smithersai/incur"
)

func main() {
	cli := incur.New("my-cli", incur.WithDescription("My CLI"))

	cli.Command("status", &incur.CommandDef{
		Description: "Show repo status",
		Handler: func(ctx *incur.CommandContext) (any, error) {
			return map[string]any{"clean": true}, nil
		},
	})

	cli.Command("install", &incur.CommandDef{
		Description: "Install a package",
		ArgsSchema: &incur.JSONSchema{
			Type: "object",
			Properties: map[string]*incur.JSONSchema{
				"package": {Type: "string", Description: "Package name"},
			},
			XOrder: []string{"package"},
		},
		OptionsSchema: &incur.JSONSchema{
			Type: "object",
			Properties: map[string]*incur.JSONSchema{
				"saveDev": {Type: "boolean", Description: "Save as dev dependency"},
			},
		},
		Alias: map[string]string{"saveDev": "D"},
		Handler: func(ctx *incur.CommandContext) (any, error) {
			return map[string]any{"added": 1, "packages": 451}, nil
		},
	})

	if err := cli.Serve(os.Args[1:]); err != nil {
		os.Exit(1)
	}
}

$ my-cli status
# clean: true

$ my-cli install express -D
# added: 1
# packages: 451

Sub-command CLI

Create a separate Cli and mount it with Group.

package main

import (
	"os"

	"github.com/smithersai/incur"
)

func main() {
	root := incur.New("my-cli", incur.WithDescription("My CLI"))

	pr := incur.New("pr", incur.WithDescription("Pull request commands"))
	pr.Command("list", &incur.CommandDef{
		Description: "List pull requests",
		OptionsSchema: &incur.JSONSchema{
			Type: "object",
			Properties: map[string]*incur.JSONSchema{
				"state": {
					Type:        "string",
					Enum:        []any{"open", "closed", "all"},
					Default:     "open",
					Description: "Pull request state",
				},
			},
		},
		Handler: func(ctx *incur.CommandContext) (any, error) {
			return map[string]any{
				"prs":   []any{},
				"state": ctx.Options["state"],
			}, nil
		},
	})

	root.Group("pr", pr)

	if err := root.Serve(os.Args[1:]); err != nil {
		os.Exit(1)
	}
}

$ my-cli pr list --state closed
# prs: []
# state: closed

Mount APIs as CLIs

Mount an HTTP handler with FetchHandler. The CLI translates trailing args and curl-style flags into HTTP requests.

package main

import (
	"encoding/json"
	"net/http"
	"os"

	"github.com/smithersai/incur"
)

func main() {
	app := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")

		if r.Method == http.MethodGet && r.URL.Path == "/users" {
			_ = json.NewEncoder(w).Encode(map[string]any{
				"users": []map[string]any{{"id": 1, "name": "Alice"}},
			})
			return
		}

		if r.Method == http.MethodPost && r.URL.Path == "/users" {
			var body map[string]any
			_ = json.NewDecoder(r.Body).Decode(&body)
			_ = json.NewEncoder(w).Encode(map[string]any{"created": true, "name": body["name"]})
			return
		}

		http.NotFound(w, r)
	})

	cli := incur.New("my-cli", incur.WithDescription("My CLI"))
	cli.Command("api", &incur.CommandDef{
		Description:  "Proxy to HTTP API",
		FetchHandler: app,
	})

	if err := cli.Serve(os.Args[1:]); err != nil {
		os.Exit(1)
	}
}

$ my-cli api users
# users:
#   - id: 1
#     name: Alice

$ my-cli api users -X POST -d '{"name":"Bob"}'
# created: true
# name: Bob

Supported fetch command flags include -X/--method, -H/--header, -d/--data, and --body. Unknown long flags become query parameters, so my-cli api users --limit 5 becomes GET /users?limit=5.

FetchHandler accepts:

• http.Handler
• func(http.ResponseWriter, *http.Request)
• func(*http.Request) (*http.Response, error)
• func(*http.Request) *http.Response

Use FetchBasePath to prepend a path before forwarding:

cli.Command("api", &incur.CommandDef{
	FetchHandler:  app,
	FetchBasePath: "/api",
})

OpenAPI

Generate command definitions from an OpenAPI 3 spec with GenerateCommands.

package main

import (
	"log"
	"net/http"
	"os"

	"github.com/getkin/kin-openapi/openapi3"
	"github.com/smithersai/incur"
)

func main() {
	loader := openapi3.NewLoader()
	spec, err := loader.LoadFromFile("openapi.yaml")
	if err != nil {
		log.Fatal(err)
	}

	app := http.DefaultServeMux
	commands, err := incur.GenerateCommands(spec, app, incur.OpenAPIOptions{
		BasePath: "/api",
	})
	if err != nil {
		log.Fatal(err)
	}

	api := incur.New("api", incur.WithDescription("API commands"))
	for name, def := range commands {
		api.Command(name, def)
	}

	cli := incur.New("my-cli", incur.WithDescription("My CLI")).Group("api", api)
	if err := cli.Serve(os.Args[1:]); err != nil {
		os.Exit(1)
	}
}

If the spec has operationIds like listUsers, createUser, and getUser, users get:

$ my-cli api --help
# Commands:
#   createUser  Create a user
#   getUser     Get a user by ID
#   listUsers   List users

$ my-cli api listUsers --limit 5
$ my-cli api getUser 42
$ my-cli api createUser --name Bob

Serve CLIs as APIs

Expose a CLI as a normal http.Handler with cli.Handler().

package main

import (
	"log"
	"net/http"

	"github.com/smithersai/incur"
)

func main() {
	cli := incur.New("my-cli")
	cli.Command("users", &incur.CommandDef{
		ArgsSchema: &incur.JSONSchema{
			Type: "object",
			Properties: map[string]*incur.JSONSchema{
				"id": {Type: "number", Description: "User ID"},
			},
			XOrder: []string{"id"},
		},
		OptionsSchema: &incur.JSONSchema{
			Type: "object",
			Properties: map[string]*incur.JSONSchema{
				"limit": {Type: "number", Default: 10},
			},
		},
		Handler: func(ctx *incur.CommandContext) (any, error) {
			if ctx.Args["id"] != nil {
				return map[string]any{"id": ctx.Args["id"], "name": "Alice"}, nil
			}
			return map[string]any{
				"users": []map[string]any{{"id": 1, "name": "Alice"}},
				"limit": ctx.Options["limit"],
			}, nil
		},
	})

	log.Fatal(http.ListenAndServe(":8080", cli.Handler()))
}

Path segments map to commands and positional args, query params map to options, and POST JSON bodies map to options:

GET  /users?limit=5           -> my-cli users --limit 5
GET  /users/42                -> my-cli users 42
POST /users { "name": "Bob" } -> my-cli users --name Bob

Responses use the same JSON envelope as --full-output --format json:

{ "ok": true, "data": { "users": [] }, "meta": { "command": "users", "duration": "3ms" } }

cli.Fetch(req) runs the same handler and returns an *http.Response, which is useful in tests and in runtimes that want fetch-like request/response objects.

MCP over HTTP

The HTTP handler automatically exposes an MCP endpoint at /mcp. Non-/mcp paths keep routing to CLI commands.

POST /mcp  { "jsonrpc": "2.0", "method": "initialize", ... }
POST /mcp  { "jsonrpc": "2.0", "method": "tools/list", ... }
POST /mcp  { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "users", ... } }

Walkthrough

Agent discovery

Agents can only use your CLI if they know it exists. incur ships discovery mechanisms with every CLI:

# Generate and install agent skill files.
my-cli skills add

# List the skills incur would install for this CLI.
my-cli skills list
my-cli skills ls

# Register as an MCP server for supported agents.
my-cli mcp add

# Start as an MCP stdio server.
my-cli --mcp

# Print a compact command manifest.
my-cli --llms

# Print the full command manifest.
my-cli --llms-full

--llms defaults to Markdown. Use --format json or --format yaml for machine-readable manifests.

my-cli --llms --format json
my-cli --llms-full --format yaml
my-cli pr --llms-full

Session savings

The original incur design is built around reducing the tokens an agent spends before it can do useful work:

• MCP exposes every tool schema up front; incur skills load only a small index until a specific command group is needed.
• --llms gives agents a compact manifest without asking them to read a whole README.
• Split skills keep large CLIs discoverable by group instead of as one large file.
• TOON output removes JSON braces, repeated keys, and most quoting from command results.
• --filter-output, --token-count, --token-limit, and --token-offset let an agent inspect large outputs without consuming the whole result at once.

The practical goal is the same as upstream TypeScript incur: agents should spend fewer tokens learning a CLI and more tokens using it correctly.

Call-to-actions

Return CTAs from ctx.OK or ctx.Error to suggest follow-up commands.

cli.Command("list", &incur.CommandDef{
	Description: "List items",
	Handler: func(ctx *incur.CommandContext) (any, error) {
		items := []map[string]any{{"id": 1, "title": "Fix bug"}}
		return ctx.OK(
			map[string]any{"items": items},
			incur.ResultOptions{
				CTA: &incur.CTABlock{
					Commands: []any{
						map[string]any{
							"command":     "get",
							"args":        map[string]any{"id": 1},
							"description": "View item",
						},
						map[string]any{
							"command":     "list",
							"options":     map[string]any{"state": "closed"},
							"description": "View closed",
						},
					},
				},
			},
		), nil
	},
})

$ my-cli list
# items:
#   - id: 1
#     title: Fix bug
# Suggested commands:
#   my-cli get 1       View item
#   my-cli list --state closed  View closed

CTA command entries can be strings or objects. Object commands may include command, args, options, and description; incur folds those into a shell command and prefixes the CLI name.

TOON output

incur defaults to TOON, a readable and token-efficient structured format.

cli.Command("hikes", &incur.CommandDef{
	Handler: func(ctx *incur.CommandContext) (any, error) {
		return map[string]any{
			"context": map[string]any{
				"task":     "Our favorite hikes together",
				"location": "Boulder",
				"season":   "spring_2025",
			},
			"friends": []string{"ana", "luis", "sam"},
			"hikes": []map[string]any{
				{"id": 1, "name": "Blue Lake Trail", "distanceKm": 7.5, "wasSunny": true},
				{"id": 2, "name": "Ridge Overlook", "distanceKm": 9.2, "wasSunny": false},
			},
		}, nil
	},
})

$ my-cli hikes
# context:
#   location: Boulder
#   season: spring_2025
#   task: Our favorite hikes together
# friends[3]: ana,luis,sam
# hikes[2]{distanceKm,id,name,wasSunny}:
#   7.5,1,Blue Lake Trail,true
#   9.2,2,Ridge Overlook,false

Switch formats with --format or --json:

my-cli hikes --format json
my-cli hikes --format yaml
my-cli hikes --format md
my-cli hikes --format jsonl
my-cli hikes --json

Set defaults globally or per-command:

cli := incur.New("my-cli", incur.WithFormat(incur.FormatJSON))

cli.Command("logs", &incur.CommandDef{
	Format:  incur.FormatJSONL,
	Handler: func(ctx *incur.CommandContext) (any, error) { return []any{}, nil },
})

Well-formed I/O

Arguments, options, environment variables, and output are described with JSON Schema.

cli.Command("deploy", &incur.CommandDef{
	Description: "Deploy an environment",
	ArgsSchema: &incur.JSONSchema{
		Type: "object",
		Properties: map[string]*incur.JSONSchema{
			"env": {
				Type:        "string",
				Enum:        []any{"staging", "production"},
				Description: "Environment to deploy",
			},
		},
		Required: []string{"env"},
		XOrder:   []string{"env"},
	},
	OptionsSchema: &incur.JSONSchema{
		Type: "object",
		Properties: map[string]*incur.JSONSchema{
			"force": {Type: "boolean", Description: "Skip safety checks"},
		},
	},
	EnvSchema: &incur.JSONSchema{
		Type: "object",
		Properties: map[string]*incur.JSONSchema{
			"DEPLOY_TOKEN": {Type: "string", Description: "Deploy token"},
		},
		Required: []string{"DEPLOY_TOKEN"},
	},
	OutputSchema: &incur.JSONSchema{
		Type: "object",
		Properties: map[string]*incur.JSONSchema{
			"url":      {Type: "string"},
			"duration": {Type: "number"},
		},
		Required: []string{"url", "duration"},
	},
	Handler: func(ctx *incur.CommandContext) (any, error) {
		return map[string]any{
			"url":      "https://" + ctx.Args["env"].(string) + ".example.com",
			"duration": 3.2,
		}, nil
	},
})

Go does not have Zod or TypeScript's generic inference, so this fork uses explicit JSONSchema structs. For positional args, set XOrder when order matters.

Reusing schemas with Zod

Use JSON Schema as the shared contract between TypeScript and Go. If a TypeScript project already owns the shape in Zod, emit JSON Schema with z.toJSONSchema() during build or codegen, commit the generated .json schema, and load that same file from Go:

argsSchema, err := incur.LoadSchema("schemas/deploy.args.json")
if err != nil {
	return err
}

cli.Command("deploy", &incur.CommandDef{
	ArgsSchema: argsSchema,
	Handler:   deploy,
})

If TypeScript also needs useful z.infer types from z.fromJSONSchema(), keep or generate a tiny .ts schema module instead of importing the .json file directly. JSON module imports cannot be marked as const, so the literal schema shape is easier to preserve in TypeScript source:

import * as z from "zod"

export const deployArgsSchema = {
  type: "object",
  properties: {
    env: { type: "string", enum: ["staging", "production"] },
  },
  required: ["env"],
  additionalProperties: false,
} as const

const DeployArgs = z.fromJSONSchema(deployArgsSchema)
type DeployArgs = z.infer<typeof DeployArgs>

Then emit the same object to schemas/deploy.args.json for Go to load.

Keep the shared subset JSON Schema-friendly: primitives, objects, arrays, enums, defaults, descriptions, required, and additionalProperties. Zod transforms, custom refinements, functions, dates, maps, and sets do not round-trip cleanly because they do not have direct JSON Schema equivalents.

Streaming

Use StreamHandler to emit chunks from a channel.

cli.Command("logs", &incur.CommandDef{
	Description: "Tail logs",
	StreamHandler: func(ctx *incur.CommandContext) (<-chan any, error) {
		ch := make(chan any)
		go func() {
			defer close(ch)
			ch <- "connecting..."
			ch <- map[string]any{"line": "streaming logs"}
			ch <- map[string]any{"line": "done"}
		}()
		return ch, nil
	},
})

$ my-cli logs
# connecting...
# line: streaming logs
# line: done

With --format json, chunks are buffered into a JSON array. With --format jsonl, each chunk is emitted as a record and the stream ends with a done record.

You can yield a final CTA or an error:

ch <- ctx.OK(nil, incur.ResultOptions{
	CTA: &incur.CTABlock{Commands: []any{"status"}},
})

ch <- ctx.Error(incur.ErrorOpts{
	Code:    "STREAM_FAILED",
	Message: "stream failed",
})

Output policy

Successful output is shown to everyone by default. Set OutputPolicyAgentOnly to hide successful data in human TTY mode while still returning it to agents, JSON callers, and HTTP/MCP consumers.

cli.Command("deploy", &incur.CommandDef{
	OutputPolicy: incur.OutputPolicyAgentOnly,
	Handler: func(ctx *incur.CommandContext) (any, error) {
		return map[string]any{"id": "deploy-123", "url": "https://staging.example.com"}, nil
	},
})

Set it at the root and override per command:

internal := incur.New("internal", incur.WithOutputPolicy(incur.OutputPolicyAgentOnly))

internal.Command("sync", &incur.CommandDef{
	Handler: func(ctx *incur.CommandContext) (any, error) {
		return map[string]any{"synced": true}, nil
	},
})

internal.Command("status", &incur.CommandDef{
	OutputPolicy: incur.OutputPolicyAll,
	Handler: func(ctx *incur.CommandContext) (any, error) {
		return map[string]any{"ok": true}, nil
	},
})

CLI name and agent detection

Command and middleware contexts include the root CLI name, display name, version, command path, selected format, and whether the current consumer looks like an agent.

cli.Command("check", &incur.CommandDef{
	Handler: func(ctx *incur.CommandContext) (any, error) {
		if !ctx.Agent {
			_, _ = os.Stderr.WriteString("Running local checks...\n")
		}

		authenticated := false // Replace with your auth check.
		if !authenticated {
			return ctx.Error(incur.ErrorOpts{
				Code:    "NOT_AUTHENTICATED",
				Message: "Not logged in. Run `" + ctx.Name + " auth login`.",
			}), nil
		}

		return map[string]any{"ok": true}, nil
	},
})

Deprecated options

Mark options as deprecated with Deprecated: true. Deprecated options show in help, skill docs, and JSON schema, and produce a TTY warning when used.

cli.Command("deploy", &incur.CommandDef{
	OptionsSchema: &incur.JSONSchema{
		Type: "object",
		Properties: map[string]*incur.JSONSchema{
			"zone":   {Type: "string", Description: "Availability zone", Deprecated: true},
			"region": {Type: "string", Description: "Target region"},
		},
	},
	Handler: func(ctx *incur.CommandContext) (any, error) {
		return map[string]any{"region": ctx.Options["region"]}, nil
	},
})

$ my-cli deploy --zone us-east-1
# Warning: --zone is deprecated

Middleware

Middleware executes in registration order, onion-style. Root and group middleware run before per-command middleware.

cli := incur.New("deploy-cli", incur.WithDescription("Deploy tools"))

cli.Use(func(ctx *incur.Context, next func() error) error {
	start := time.Now()
	err := next()
	fmt.Fprintf(os.Stderr, "took %s\n", time.Since(start))
	return err
})

cli.Command("deploy", &incur.CommandDef{
	Handler: func(ctx *incur.CommandContext) (any, error) {
		return map[string]any{"deployed": true}, nil
	},
})

Middleware can short-circuit with a structured error:

requireAuth := func(ctx *incur.Context, next func() error) error {
	if ctx.Get("user") == nil {
		ctx.Error(incur.ErrorOpts{
			Code:    "AUTH",
			Message: "must be logged in",
		})
		return nil
	}
	return next()
}

cli.Command("deploy", &incur.CommandDef{
	Middleware: []incur.MiddlewareFunc{requireAuth},
	Handler: func(ctx *incur.CommandContext) (any, error) {
		return map[string]any{"deployed": true}, nil
	},
})

Variables

Use WithVars to declare middleware variables and ctx.Set / ctx.Get to pass values to downstream middleware and command handlers.

cli := incur.New("my-cli",
	incur.WithVars(&incur.JSONSchema{
		Type: "object",
		Properties: map[string]*incur.JSONSchema{
			"user":      {Type: "string"},
			"requestId": {Type: "string"},
			"debug":     {Type: "boolean", Default: true},
		},
	}),
	incur.WithMiddleware(func(ctx *incur.Context, next func() error) error {
		ctx.Set("user", "alice")
		ctx.Set("requestId", "req_123")
		return next()
	}),
)

cli.Command("whoami", &incur.CommandDef{
	Handler: func(ctx *incur.CommandContext) (any, error) {
		return map[string]any{
			"user":      ctx.Get("user"),
			"requestId": ctx.Get("requestId"),
			"debug":     ctx.Get("debug"),
		}, nil
	},
})

Config file

Load option defaults from JSON config files with WithConfig.

cli := incur.New("my-cli",
	incur.WithConfig("my-cli.json", "~/.config/my-cli/config.json"),
)

This registers --config <path> and --no-config. First existing file wins unless overridden.

{
  "options": {
    "verbose": true
  },
  "commands": {
    "echo": {
      "options": {
        "upper": true,
        "prefix": "cfg"
      }
    },
    "project": {
      "commands": {
        "list": {
          "options": {
            "limit": 25,
            "save-dev": true
          }
        }
      }
    }
  }
}

Precedence is argv > config > schema defaults. Only command options are loaded; args, env, and built-in commands are unaffected.

Customize the flag or loader:

cli := incur.New("my-cli",
	incur.WithConfigOptions(incur.ConfigOptions{
		Files: []string{"my-cli.yaml"},
		Flag:  "--settings",
		Loader: func(path string) (map[string]any, error) {
			// Load YAML, TOML, remote config, etc.
			return map[string]any{}, nil
		},
	}),
)

Generate a JSON Schema for config files programmatically:

schema := incur.ConfigSchemaFromCli(cli)

Filtering output

Use --filter-output to prune command output to specific keys. It supports dot notation, array slices, and comma-separated paths.

cli.Command("users", &incur.CommandDef{
	Handler: func(ctx *incur.CommandContext) (any, error) {
		return map[string]any{
			"users": []map[string]any{
				{"name": "Alice", "email": "alice@example.com", "role": "admin"},
				{"name": "Bob", "email": "bob@example.com", "role": "user"},
				{"name": "Carol", "email": "carol@example.com", "role": "user"},
			},
		}, nil
	},
})

$ my-cli users --filter-output users.name
# [3]: Alice,Bob,Carol

$ my-cli users --filter-output users[0,2].name
# users[2]{name}:
#   Alice
#   Bob

Token pagination

Use --token-count, --token-limit, and --token-offset to manage large outputs. Token counts are estimates intended for agent-friendly pagination.

# Check output size.
my-cli users --token-count

# Limit output to the first page.
my-cli users --token-limit 200

# Read the next page.
my-cli users --token-offset 200 --token-limit 200

Command schema

Use --schema to inspect a command's JSON Schema.

my-cli install --schema
my-cli install --schema --format json
my-cli pr list --schema --format yaml

The schema output includes arguments, options, environment variables, and output when declared.

Shell completions

Every incur CLI has a built-in completions command.

# bash
eval "$(my-cli completions bash)"

# zsh
eval "$(my-cli completions zsh)"

# fish
my-cli completions fish | source

# nushell
my-cli completions nushell

Completions are dynamic: commands, command groups, aliases, options, short aliases, and enum values are suggested from the registered command tree.

Global options

Every incur CLI includes global options:

Flag	Description
--filter-output <keys>	Filter output by key paths such as foo,bar.baz,a[0,3]
--format <toon|json|yaml|md|jsonl>	Select output format
--full-output	Include the full envelope: ok, data or error, and meta
--help	Show help
--json	Shorthand for --format json
--llms	Print a compact LLM-readable command manifest
--llms-full	Print the full LLM-readable command manifest
--mcp	Start as an MCP stdio server
--schema	Show JSON Schema for a command
--token-count	Print token count instead of output
--token-limit <n>	Limit output to n tokens
--token-offset <n>	Skip the first n output tokens
--version	Show CLI version
--config <path>	Load JSON option defaults when config is enabled
--no-config	Disable config loading when config is enabled

Errors

Return structured errors with ctx.Error:

return ctx.Error(incur.ErrorOpts{
	Code:      "NOT_AUTHENTICATED",
	Message:   "must be logged in",
	Retryable: false,
	CTA: &incur.CTABlock{
		Description: "Authenticate to continue:",
		Commands:    []any{"auth login"},
	},
}), nil

Or return Go errors. NewIncurError, NewValidationError, and NewParseError preserve structured details and integrate with errors.Is / errors.As.

return nil, incur.NewIncurError(incur.IncurErrorOptions{
	Code:    "LOCKED",
	Message: "resource locked",
	Hint:    "Try again after the current deployment finishes.",
})

Code generation

The cmd/incur helper can generate Go structs and command registration code from JSON Schema files.

# incur.yaml
package: main
output: incur_generated.go
commands:
  - name: greet
    description: Greet someone
    args: schemas/greet.args.json
    output: schemas/greet.output.json
    handler: Greet

incur gen
incur gen path/to/incur.yaml
incur generate
incur generate path/to/incur.yaml

The generated source includes schema-backed structs, embedded schemas, and RegisterCommands(cli *incur.Cli).

API Reference

Core API

cli := incur.New("name",
	incur.WithDescription("Description"),
	incur.WithVersion("1.0.0"),
	incur.WithAliases("alias"),
	incur.WithFormat(incur.FormatTOON),
	incur.WithOutputPolicy(incur.OutputPolicyAll),
	incur.WithConfig("name.json"),
	incur.WithEnv(envSchema),
	incur.WithVars(varsSchema),
	incur.WithMiddleware(middleware...),
	incur.WithRootCommand(rootDef),
)

cli.Command("command name", def)
cli.Group("group", subCli)
cli.Use(middleware)
err := cli.Serve(os.Args[1:])
handler := cli.Handler()
resp := cli.Fetch(req)

CommandDef

type CommandDef struct {
	Name          string
	Description   string
	ArgsSchema    *incur.JSONSchema
	OptionsSchema *incur.JSONSchema
	EnvSchema     *incur.JSONSchema
	OutputSchema  *incur.JSONSchema
	Format        incur.Format
	Alias         map[string]string
	Aliases       []string
	Usage         string
	Hint          string
	Examples      []incur.Example
	Middleware    []incur.MiddlewareFunc
	Handler       incur.CommandHandler
	StreamHandler incur.StreamHandler
	FetchHandler  any
	FetchBasePath string
	OutputPolicy  incur.OutputPolicy
}

JSONSchema

JSONSchema covers the subset of JSON Schema incur needs for CLI parsing, help, manifests, validation, OpenAPI import, and codegen:

type JSONSchema struct {
	Type                 any
	Properties           map[string]*incur.JSONSchema
	Required             []string
	Items                *incur.JSONSchema
	Enum                 []any
	Default              any
	Description          string
	Const                any
	AnyOf                []*incur.JSONSchema
	Ref                  string
	Defs                 map[string]*incur.JSONSchema
	Format               string
	Deprecated           bool
	AdditionalProperties any
	XCount               bool
	XOrder               []string
}

Use ParseSchema, LoadSchema, and Validate when you want schemas from files or custom validation outside a CLI run.

Current status

• This fork tracks the original TypeScript incur where that makes sense for Go.
• The Go API is intentionally close in spirit, but not identical: schemas are explicit structs instead of Zod schemas, and Go cannot infer run callback types the same way TypeScript can.
• Upstream test behavior is tracked at case level rather than approximated with smoke tests. See TEST_PARITY.md and TEST_PARITY_CASES.md, and run make verify-parity with an upstream checkout to detect stale mappings.
• APIs may evolve before stable releases. Pin a commit if you need reproducible builds.

Contributing

PRs are welcome for bugs, parity gaps, docs, tests, and Go-specific improvements. For broad product or API design changes, check the upstream wevm/incur direction first so this fork stays recognizable.

License

MIT. See LICENSE.