cli-app-developmentlisted
Install: claude install-skill wibus-wee/cradle-app
# 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:
```typescript
'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 o