DevRel Tooling

Build the tools your developers reach for daily: CLIs they tab-complete without thinking, API collections they import on day one.

Two domains:

State which domain you need, or describe what you're building.

CLI tools

For expanded implementation patterns per language (Node.js/commander, Python/click+typer, Go/cobra), load references/cli-patterns.md.

Core workflow

1. Analyze UX: Map user workflows, identify common tasks, plan command hierarchy
2. Design commands: Subcommands, flags, arguments, configuration layers
3. Implement: Build with the right framework for the language
4. Polish: Completions, help text, error messages, progress indicators
5. Test: Cross-platform smoke tests; target startup < 50ms

Command hierarchy

Design the tree before writing code:

mytool                           # Root
├── init [options]              # Setup
├── config
│   ├── get <key>              # Nested subcommands
│   ├── set <key> <value>
│   └── list
├── deploy [environment]        # Positional + flags
│   ├── --dry-run
│   ├── --force
│   └── --config <file>
└── plugins
    ├── install <name>
    ├── list
    └── remove <name>

Rules:

• Positional arguments for required inputs
• Flags for optional behavior
• Short + long forms for common flags (-v, --verbose)
• Consistent naming across subcommands

Quick-start example (Node.js / commander)

#!/usr/bin/env node
const { program } = require('commander');

program.name('mytool').description('Developer platform CLI').version('1.0.0');

program
  .command('deploy <environment>')
  .description('Deploy to target environment')
  .option('-f, --force', 'skip confirmation')
  .option('-d, --dry-run', 'preview changes')
  .action((env, opts) => {
    if (!opts.force && env === 'production') {
      // prompt for confirmation in interactive mode
    }
    console.log(`Deploying to ${env}...`);
  });

program.parse();

For Python (click/typer) and Go (cobra) examples, load references/cli-patterns.md.

Error messages

Every CLI error follows: context → problem → solution. Never show raw stack traces or codes like ENOENT.

Framework selection

Use commander (Node.js), click/typer (Python), or cobra (Go). For details and alternatives, load references/cli-patterns.md.

Constraints

Must do:

• Keep startup under 50ms
• Support --help and --version
• Handle SIGINT (Ctrl+C) gracefully
• Provide shell completions (bash/zsh/fish)
• Write logs/diagnostics to stderr, output to stdout
• Test on Windows, macOS, and Linux

Must not:

• Use colors when output is not a TTY
• Require interactive input in CI environments
• Break existing command signatures (treat flag renames as breaking changes)
• Hardcode paths: use os.homedir() / Path.home() / os.UserHomeDir()

API collection generation

For the full Postman collection v2.1 schema and framework-specific scanner implementations, load references/api-collection-generators.md.

Core workflow

1. Scan routes: Find all API route definitions in the codebase
2. Extract metadata: Methods, paths, params, request bodies, headers
3. Organize: Group endpoints by resource or folder structure
4. Generate: Create Postman Collection v2.1 JSON (or OpenAPI)
5. Add examples: Include realistic request/response examples
6. Configure: Environment variables for base URL, auth tokens

Supported frameworks

Collection structure

{
  "info": {
    "name": "My API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Users",
      "item": [
        {
          "name": "GET users",
          "request": {
            "method": "GET",
            "url": { "raw": "{{baseUrl}}/users", "host": ["{{baseUrl}}"], "path": ["users"] }
          }
        }
      ]
    }
  ],
  "variable": [
    { "key": "baseUrl", "value": "http://localhost:3000/api" },
    { "key": "authToken", "value": "" }
  ]
}

Best practices

• Use Postman variables ({{baseUrl}}, {{authToken}}) for environment flexibility
• Group endpoints by resource, not by HTTP method
• Include request bodies with realistic example data for POST/PUT/PATCH
• Add endpoint descriptions explaining what each operation does
• Configure collection-level auth (bearer, basic, or API key)
• Create a matching environment template (dev, staging, production)
• Commit the generated collection to the repo: regenerate on route changes in CI

Phase gates

CLI: after implementation: Run mytool --help and verify all commands render. Run mytool --version. Test in non-interactive mode: CI=true mytool deploy staging --force.

CLI: before release: Generate completions and test in bash/zsh: source <(mytool completion bash) && mytool <TAB>. Run on macOS, Linux, and Windows (or CI matrix).

API collection: after generation: Validate the JSON: npx ajv validate -s postman-collection-v2.1-schema.json -d collection.json. Import into Postman and confirm all endpoints render.

Quality checklist

CLI tools

• --help renders correctly for all commands
• Shell completions work (bash, zsh, fish)
• Startup time < 50ms
• Works in CI/non-interactive mode
• Error messages include remediation steps
• Colors disabled when not TTY

API collections

• All routes scanned from codebase
• Endpoints grouped by resource
• Path parameters extracted and documented
• Request bodies included for POST/PUT/PATCH
• Environment variables configured
• Collection imports cleanly in Postman

When to switch skills

• Client library, types, or npm publish → sdk-craft
• MCP server tools or transport → mcp-server-craft

Did this help?

At the end of every session, ask: "Did this solve what you were trying to do?"

• If yes: done.
• If a command tree was wrong, completions failed, or the collection missed a route: encourage the user to file an issue at https://github.com/saif-shines/devex-kit/issues. Offer to help draft it. Include the domain (CLI or collection) and what was missing.