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

Metadata

Release files for csrd-utils 0.5.29

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for csrd-utils 0.5.29
File	Size	Uploaded
csrd_utils-0.5.29.tar.gz	118.0 kB	Jul 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for csrd-utils 0.5.29
File	Interpreter	ABI	Platform	Reset
csrd_utils-0.5.29-py3-none-any.whl 166.5 kB Jul 26, 2026	Python 3	none	any	Details

Total release size: 284.5 kB

Release files / csrd_utils-0.5.29.tar.gz

Download URL	csrd_utils-0.5.29.tar.gz
Size	118.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`d57935462cbf3334db930ab5dbdae62302700c4a981a5173c5f823e10c2cc73f`
BLAKE2b-256 checksum How to use checksums	`28356953c2d07e2fab7239177c1e16eccc878f883312a222f2ed00997378161d`
Upload date	Jul 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/csrd-api/fastapi-common
Publishing commit: github.com/csrd-api/fastapi-common/tree/d16e6c9f41b447dcc3e9f5c1d9388f463b33e322

Workflow

Publishing configuration: github.com/csrd-api/fastapi-common/blob/d16e6c9f41b447dcc3e9f5c1d9388f463b33e322/.github/workflows/release.yml
Publishing logs: github.com/csrd-api/fastapi-common/actions/runs/30204600049/attempts/1

Artifact

Subject: csrd_utils-0.5.29.tar.gz
SHA-256 checksum: d57935462cbf3334db930ab5dbdae62302700c4a981a5173c5f823e10c2cc73f Verifying attestations

Release files / csrd_utils-0.5.29-py3-none-any.whl

Download URL	csrd_utils-0.5.29-py3-none-any.whl
Size	166.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`11ca8dcb596ed593d7e5c48d0ff8bd79d1b1684f889dba35da9fdcb6b198486c`
BLAKE2b-256 checksum How to use checksums	`28969e4fd918408428ae93f66c68b573b183a7e3390efe5a651260528e911037`
Upload date	Jul 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/csrd-api/fastapi-common
Publishing commit: github.com/csrd-api/fastapi-common/tree/d16e6c9f41b447dcc3e9f5c1d9388f463b33e322

Workflow

Publishing configuration: github.com/csrd-api/fastapi-common/blob/d16e6c9f41b447dcc3e9f5c1d9388f463b33e322/.github/workflows/release.yml
Publishing logs: github.com/csrd-api/fastapi-common/actions/runs/30204600049/attempts/1

Artifact

Subject: csrd_utils-0.5.29-py3-none-any.whl
SHA-256 checksum: 11ca8dcb596ed593d7e5c48d0ff8bd79d1b1684f889dba35da9fdcb6b198486c Verifying attestations