csrd-utils 0.5.21

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

# Workspace-level generation (compose-based)
csrd generate                                     # interactive menu (context-aware)
csrd generate workspace --name my-ws              # create empty workspace
csrd generate preset --name my-ws                 # create workspace from preset
csrd generate add-service --name inventory        # add service to current workspace
csrd generate rename-service --service-name old-service --new-name new-service
csrd generate remove-service --service-name old   # remove service from spec
csrd generate add-infra --infra-type postgres     # add infra to workspace
csrd generate remove-infra --infra-type postgres  # remove infra from workspace
csrd generate add-augment                         # interactive augment selection
csrd generate list-augments                       # list available augments

# Feature augmentation
csrd feature list
csrd feature plan workers --service .
csrd feature plan workers --service . --json
csrd feature add workers --service .

# Diagnostics
csrd doctor --service .
csrd audit                                        # workspace-aware: scans all services
csrd audit --service .                            # explicitly audit one service path

# Shell completion
csrd completion bash                              # print bash completion script
csrd completion install                           # install to ~/.local/share/bash-completion/
csrd completion uninstall                         # remove installed completion

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

Bash tab completion

Install completion (one-time, persists across shells):

csrd completion install

This writes a completion script to ~/.local/share/bash-completion/completions/csrd, which bash auto-loads — no .bashrc edit needed. To remove: csrd completion uninstall.

Manual alternative:

source <(csrd completion bash)

Non-TTY mode

Set CSRD_NO_TTY=1 to force numbered-fallback prompts instead of the arrow-key TUI. Useful for manual testing or piping input:

CSRD_NO_TTY=1 csrd generate

Interactive generation behavior

• csrd generate shows a context-aware menu (workspace actions when inside a workspace, workspace creation otherwise).
• Services, augments, and infra are managed via csrd-compose.yaml (the workspace spec).
• csrd generate rename-service renames the service in the spec, renames src/, tests/, and Dockerfile.*, and rewrites Python imports and string references.
• All yes/no prompts default to No (y/N).

Typical workflow

# 0) Create a workspace and add services
csrd generate workspace --name local-dev
cd local-dev
csrd generate add-service --name inventory --features database --port 8081
csrd generate add-service --name pricing --port 8082

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

# 1b) Audit for weak/insecure defaults
csrd audit

# 2) Inspect available bundled features
csrd feature list

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

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

# 5) Rename a service
csrd generate rename-service --service-name pricing-service --new-name billing-service

Bundled assets

• features/workers/ feature manifests and fragments
• templates/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/FUTURE_WORK.md - remaining provider-specific CI wiring work (Phase 5B)
• 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 generate --help
csrd feature --help
csrd doctor --help
csrd audit --help
csrd completion --help
csrd feature list
csrd generate list-augments

Then run a clean smoke flow:

mkdir -p /tmp/csrd-smoke && cd /tmp/csrd-smoke
csrd generate workspace --name ws
cd ws
csrd generate add-service --name demo-svc --port 8080
csrd doctor --service .
csrd audit
csrd feature plan workers --service .
csrd feature add workers --service .
csrd generate rename-service --service-name demo-svc-service --new-name renamed-svc