csrd-utils 0.3.40

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 workspace                                # create workspace, then choose none/service/cluster
csrd new service                                  # requires workspace; prompts to create one if missing
csrd new service --interactive --name items       # pre-fills name prompt with 'items'
csrd new service --name inventory --no-interactive --output ./my-workspace
csrd new service --name pricing --output ./my-workspace --no-interactive
csrd new cluster --spec ./cluster.yaml --output ./my-workspace
csrd new cluster                                  # requires workspace; interactive mode can offer to create one
csrd feature list
csrd feature plan workers --service .
csrd feature plan workers --service . --json
csrd feature add workers --service .
csrd doctor --service .
csrd audit                                          # if cwd is workspace, audits all services
csrd audit --service .                              # explicitly audit one service path
csrd completion bash                                # print bash completion script

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

Bash tab completion

Enable command/subcommand completion in bash:

source <(csrd completion bash)

Then examples like csrd ne<TAB> and csrd new wor<TAB> complete to new and workspace.

Workspace extraction command

Service extraction into a sibling workspace is supported:

csrd workspace extract-service --service ./source-ws/src/pricing --target-workspace ../pricing-ws --mode copy
csrd workspace extract-service --service ./source-ws/src/pricing --target-workspace ../pricing-ws --mode move
csrd workspace extract-service --service ./source-ws/src/pricing --target-workspace ../pricing-ws --dry-run --json

Use extraction when service ownership diverges, release cadence becomes independent, or workspace orchestration starts coupling unrelated deployments.

Manual fallback remains available if needed:

csrd new workspace --name pricing-ws --output .. --generate none
cp -a ./source-ws/src/pricing ../pricing-ws/src/pricing
cd ../pricing-ws
csrd new cluster --spec ./.csrd/cluster.yaml --output . --force

Interactive generation behavior

• csrd new service and csrd new cluster are workspace-first commands.
• If a workspace marker is missing in the selected output path, interactive flows ask to create one and continue.
• Non-interactive generation errors when no workspace marker is present.
• Workspace cluster source of truth is persisted at .csrd/cluster.yaml.
• If .csrd/cluster.yaml already exists, csrd new service appends the generated service and refreshes scaffold files (docker-compose.yml, .env.example, README.md, smoke.sh). Service source directories and running containers are never touched.
• If .csrd/cluster.yaml is missing, csrd new service bootstraps .csrd/cluster.yaml and writes initial cluster scaffold files.
• csrd new service runs a compact interactive flow by default (core prompts 1-6), then asks whether to show advanced options.
• csrd new workspace creates a workspace directory and prompts whether to generate none, service, or cluster immediately.
• 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) Create a workspace and generate a service inside it
csrd new workspace --name local-dev --output . --generate none
csrd new service --name inventory --output ./local-dev --database postgres --workers

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

# 1b) Audit for weak/insecure defaults
csrd audit --service ./local-dev/src/inventory

# 2) Inspect available bundled features
csrd feature list

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

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

# 5) Add a second service — workspace auto-upgrades to cluster
csrd new service --name pricing --output ./local-dev --database postgres

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/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 new --help
csrd new workspace --help
csrd new service --help
csrd new cluster --help
csrd feature --help
csrd doctor --help
csrd audit --help
csrd feature list

Then run a clean smoke flow:

mkdir -p /tmp/csrd-smoke
csrd new workspace --name ws --output /tmp/csrd-smoke --generate none
csrd new service --name demo-svc --output /tmp/csrd-smoke/ws --no-interactive
csrd doctor --service /tmp/csrd-smoke/ws/src/demo-svc
csrd audit --service /tmp/csrd-smoke/ws/src/demo-svc
csrd feature plan workers --service /tmp/csrd-smoke/ws/src/demo-svc
csrd feature add workers --service /tmp/csrd-smoke/ws/src/demo-svc