# Cli Design

> Design a CLI interface: args, flags, help, output, errors, exit codes, config.

- **Type:** Skill
- **Install:** `agentstack add skill-notque-vexjoy-agent-cli-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [notque](https://agentstack.voostack.com/s/notque)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [notque](https://github.com/notque)
- **Source:** https://github.com/notque/vexjoy-agent/tree/main/skills/engineering/cli-design
- **Website:** https://vexjoy.com

## Install

```sh
agentstack add skill-notque-vexjoy-agent-cli-design
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# CLI Design

Design a command-line tool's interface before implementation: human-first, script-friendly, Linux-only. Output is a compact spec the user or an agent can implement directly. Rubric source: clig.dev (rebuilt as `references/clig-checklist.md`).

## Workflow

### Phase 1: SCOPE

Lock the interface with the minimum questions. Proceed with the conventions in Phase 2 when the user is unsure.

- Command name and one-sentence purpose.
- Primary user: humans, scripts, or both.
- Input sources: args vs stdin; files vs URLs. Secrets travel via file or stdin, because flags leak through `ps` and shell history.
- Output contract: human text, `--json`, `--plain`, exit codes.
- Interactivity: prompts allowed? `--no-input` needed? confirmation for destructive ops?
- Config model: flags, env, config file; precedence.

**Gate:** name, purpose, and I/O contract are known. Proceed only when gate passes.

### Phase 2: DESIGN

Load [references/clig-checklist.md](references/clig-checklist.md) and apply it as the default rubric. For each section, pick the convention and record it in the spec. Diverge from a convention only deliberately, and document the divergence in the spec — interfaces are contracts, and surprising contracts break scripts.

### Phase 3: DELIVER

Produce the spec from this skeleton. Drop a section only when it genuinely has no content; fill every other section.

1. **Name and one-liner**: command name plus a single sentence of purpose
2. **Usage line**: the synopsis as `--help` will print it, global flags and subcommand slot included
3. **Subcommands**: purpose of each, whether it mutates state, whether re-running it is safe
4. **Args/flags table**: columns for name, type, default, required?, example
5. **I/O contract**: primary data and machine-readable output on stdout; everything else (errors, progress, logs) on stderr
6. **Exit codes**: map each failure mode to a code — success `0`, failure `1`, bad usage `2`; mint extra codes only for cases scripts must distinguish
7. **Safety**: `--dry-run`, confirmation rules, `--force`, `--no-input`
8. **Env/config**: env vars; config file path; precedence order with flags highest, then env, project config, user config, system
9. **Examples**: enough invocations to cover the common flows; show at least one pipeline or stdin use

**Gate:** every flag used in the examples appears in the flags table, and every failure mode shown maps to an exit code.

## Constraints

- Stay at spec altitude: when the request is "design the interface," deliver the spec and stop. Implementation is a separate task.
- Keep the spec language-agnostic. Recommend a parsing library only when asked.
- Target Linux. Skip Windows/macOS path, signal, and packaging concerns.

## Error handling

### Request mixes design and implementation
Cause: user says "design and build."
Solution: deliver the spec first, get confirmation, then implement against it.

### Spec balloons past one page
Cause: subcommand sprawl or speculative flags.
Solution: cut flags that lack a named user need; defaults should serve most users without aliases.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [notque](https://github.com/notque)
- **Source:** [notque/vexjoy-agent](https://github.com/notque/vexjoy-agent)
- **License:** MIT
- **Homepage:** https://vexjoy.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-notque-vexjoy-agent-cli-design
- Seller: https://agentstack.voostack.com/s/notque
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.