cli-app-development

name	cli-app-development
description	Use when modifying Cradle packages/cli, the OpenAPI-to-CLI generator, generated command runtime, output formats, command registration, or validation workflow for the generated Cradle CLI.

CLI App Development

Use this skill for packages/cli work. Cradle CLI is generated-first and Agent-oriented: default output should be readable for humans, while structured data must remain explicit and predictable for shell pipelines.

Architecture

The CLI package has two layers:

• src/runtime: stable runtime helpers for HTTP requests, command registration, output formatting, and execution context.
• src/commands/generated: generated command modules created by pnpm gen:cli.

The generator is scripts/generate-cli.ts:

• It creates an in-process apps/server Elysia app.
• It reads /openapi.json.
• It finds operations with x-cradle-cli.command.
• It infers arguments and flags from OpenAPI path/query/body schemas.
• It writes one TypeScript command module per command plus index.generated.ts.

Do not manually edit files in src/commands/generated. Change the server route metadata or generator/runtime, then regenerate.

Command Contract

Server route metadata controls only command placement:

'x-cradle-cli': {
  command: ['workspace', 'git', 'status'],
  defaultWorkspaceId: true, // optional ambient workspace
  // defaultChatSessionId: true, // optional ambient chat session
}

Generator responsibilities:

• Path parameters -> positional arguments.
• Query parameters -> --kebab-case flags.
• Body object properties -> --kebab-case flags.
• Required schema fields -> Commander required options.
• Array schema fields -> comma-separated or repeated string input handling.
• Object schema fields -> JSON string parsing.
• Enum schema fields -> allowed values in help text.
• defaultWorkspaceId: true -> workspace name/id resolver with ambient env/cwd fallback.
• defaultChatSessionId: true -> envDefault: 'CRADLE_CHAT_SESSION_ID' on chat-session id fields (makes path [id] optional).

Output Philosophy

Default output is gh-style auto: render lists as bordered terminal tables when scalar columns exist, render acknowledgements as short text, and fall back to pretty JSON when the shape is too nested to display safely.

Agents should request structured output explicitly:

Supported formats:

--json
--json id,name,status
--format auto
--format json
--format pretty
--format table
--format ndjson

Do not add built-in filtering, sorting, or query languages unless there is a strong product reason. Agents can compose those with standard shell tools. Top-level field selection belongs to --json <fields> because it mirrors gh CLI and keeps common Agent calls compact.

Development Workflow

1. If adding commands, prefer adding x-cradle-cli.command to server routes first.
2. If schema inference is wrong, fix scripts/generate-cli.ts; do not patch generated command files.
3. If command execution or output is wrong, fix src/runtime.
4. Regenerate commands:

pnpm gen:cli

5. Validate the CLI package:

pnpm --filter @cradle/cli typecheck
pnpm --filter @cradle/cli cradle --help

6. Check representative nested command help for the area changed:

pnpm --filter @cradle/cli cradle workspace --help
pnpm --filter @cradle/cli cradle issue --help

Safety Rules

• Do not expose secret value writes as generated flags unless the product explicitly accepts shell-history risk.
• Do not generate plain commands for SSE streams or PTY interactive endpoints.
• Keep generated command modules deterministic and simple.
• Keep runtime helpers small; the server OpenAPI contract should remain the source of truth.
• If a route is omitted intentionally, document the omission in the server module README or final response.

Completion Checklist

Before calling CLI work done:

• pnpm gen:cli succeeds.
• pnpm --filter @cradle/cli typecheck succeeds.
• Generated commands no longer require manual operation IDs.
• The command count and top-level groups match the intended server exposure.
• Representative --help output shows inferred arguments and flags.