csrd-utils 0.3.9

CLI utilities for csrd service generation and feature augmentation

csrd-utils

CLI and runtime helpers for generating csrd services and augmenting existing services with optional features.

Install

pip install "csrd-utils @ git+https://github.com/csrd-api/fastapi-common.git#subdirectory=packages/utils"

CLI

csrd --help
csrd --version
csrd new service                                  # compact interactive mode (prompts 1-6, then advanced gate)
csrd new service --interactive --name items       # pre-fills name prompt with 'items'
csrd new service --name inventory --no-interactive --output .
csrd new cluster --spec ./cluster.yaml --output .
csrd new cluster                                  # interactive cluster builder (preset + service prompts)
csrd feature list
csrd feature plan workers --service .
csrd feature plan workers --service . --json
csrd feature add workers --service .
csrd doctor --service .

feature plan --json is useful for CI or tooling wrappers.

Interactive generation behavior

• csrd new service runs a compact interactive flow by default (core prompts 1-6), then asks whether to show advanced options.
• In compact mode, advanced options are hidden by default.
• csrd new service --interactive runs the full verbose interactive flow.
• Passing --name <value> in interactive mode uses that value as the name prompt default.
• You can still overwrite the default by entering a different value at the prompt.
• Use --no-interactive for fully flag-driven generation.
• Database default is none.
• All yes/no prompts default to No (y/N).

Typical workflow

# 0) Generate a new service from bundled template
csrd new service --name inventory --output . --database postgres --workers

# 1) Verify service compatibility
csrd doctor --service ./inventory

# 2) Inspect available bundled features
csrd feature list

# 3) Dry-run a feature
csrd feature plan workers --service ./inventory

# 4) Apply feature files/merges
csrd feature add workers --service ./inventory

Bundled assets

• features/workers/ feature manifests and fragments
• templates/cookiecutter-service/ template starter

Python API

from pathlib import Path
from csrd_utils import ServiceAugmentor
from csrd_utils.resources import features_path

with features_path() as feature_lib:
    augmentor = ServiceAugmentor(Path("."), feature_lib)
    ok, changes = augmentor.add_feature("workers", plan=True)

Documentation

• docs/CLI_REFERENCE.md - full command/flag reference
• docs/FEATURES.md - bundled feature catalog and behavior
• docs/AGENT_SMOKE_TESTS.md - copy/paste validation flow for clean workspaces
• docs/COMMAND_MATRIX.yaml - machine-readable command matrix for automation
• AGENTS.md - package-local rules for autonomous agents

CLI-only agent mode

If an agent can only see the installed CLI (not source files), use this exploration sequence:

csrd --help
csrd new --help
csrd new cluster --help
csrd feature --help
csrd doctor --help
csrd feature list

Then run a clean smoke flow:

mkdir -p /tmp/csrd-smoke
cd /tmp/csrd-smoke
csrd new service --name demo-svc --output . --no-interactive
cd demo-svc
csrd doctor
csrd feature plan workers
csrd feature add workers