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.7.0

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.7.0
File	Size	Uploaded
csrd_utils-0.7.0.tar.gz	127.6 kB	Oct 16, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for csrd-utils 0.7.0
File	Interpreter	ABI	Platform	Reset
csrd_utils-0.7.0-py3-none-any.whl 177.6 kB Oct 16, 2026	Python 3	none	any	Details

Total release size: 305.2 kB

Release files / csrd_utils-0.7.0.tar.gz

Download URL	csrd_utils-0.7.0.tar.gz
Size	127.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`4388dff940898a3d85cba0267160af661bba6148cbd8162c3c39c91928e69062`
BLAKE2b-256 checksum How to use checksums	`4f8691bdd76bbff4955e19f7f6b175168d99d079e997a1099f294648977dda11`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.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/d6d759c818d70dd038c8905a88a297258ec1b5ac

Workflow

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

Artifact

Subject: csrd_utils-0.7.0.tar.gz
SHA-256 checksum: 4388dff940898a3d85cba0267160af661bba6148cbd8162c3c39c91928e69062 Verifying attestations

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

Download URL	csrd_utils-0.7.0-py3-none-any.whl
Size	177.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`64cc78bbb3263c10431db2f13e9f7c4c41fbaa1490abaacc153290a3df5fdfa1`
BLAKE2b-256 checksum How to use checksums	`5d0627232710b0e183d7b09db1a5063848ca837716678ef04fcd08778361f405`
Upload date	Oct 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.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/d6d759c818d70dd038c8905a88a297258ec1b5ac

Workflow

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

Artifact

Subject: csrd_utils-0.7.0-py3-none-any.whl
SHA-256 checksum: 64cc78bbb3263c10431db2f13e9f7c4c41fbaa1490abaacc153290a3df5fdfa1 Verifying attestations