Command-Line Interface

Every cursus command, subcommand, option, and argument below is rendered directly from the live Click application (cursus.cli:cli), so this reference never drifts from the installed CLI.

cursus

Cursus — specification-driven SageMaker pipeline development and validation.

Usage

cursus [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

alignment

Unified Alignment Tester for Cursus Scripts.

Validates alignment across all four levels: 1. Script ↔ Contract Alignment 2. Contract ↔ Specification Alignment 3. Specification ↔ Dependencies Alignment 4. Builder ↔ Configuration Alignment

Updated to work with the refactored validation system and step catalog integration.

Usage

cursus alignment [OPTIONS] COMMAND [ARGS]...

list-scripts

List all available scripts that can be validated.

Discovers all Python scripts using the step catalog (workspace-aware).

Example:

cursus alignment list-scripts cursus alignment list-scripts –workspace-dirs /path/to/workspace

Usage

cursus alignment list-scripts [OPTIONS]

Options

--workspace-dirs <workspace_dirs>

Workspace directories to include in validation

validate

Validate alignment for a specific script.

SCRIPT_NAME: Name of the script to validate (without .py extension)

Example:

cursus alignment validate currency_conversion –verbose cursus alignment validate dummy_training –output-dir ./reports

Usage

cursus alignment validate [OPTIONS] SCRIPT_NAME

Options

--workspace-dirs <workspace_dirs>

Workspace directories to include in validation

-o, --output-dir <output_dir>

Output directory for the JSON report

-v, --verbose

Show detailed output

--show-scoring

Show alignment scoring information

Arguments

SCRIPT_NAME

Required argument

validate-all

Validate alignment for all scripts discovered by the step catalog.

Discovers all Python scripts using the step catalog (workspace-aware) and runs comprehensive alignment validation for each one, generating detailed reports.

Example:

cursus alignment validate-all –output-dir ./reports –verbose

Usage

cursus alignment validate-all [OPTIONS]

Options

--workspace-dirs <workspace_dirs>

Workspace directories to include in validation

-o, --output-dir <output_dir>

Output directory for JSON reports

-v, --verbose

Show detailed output

--show-scoring

Show alignment scoring information

--continue-on-error

Continue validation even if individual scripts fail

validate-level

Validate alignment for a specific script at a specific level.

SCRIPT_NAME: Name of the script to validate (without .py extension) LEVEL: Validation level (1=Script↔Contract, 2=Contract↔Spec, 3=Spec↔Deps, 4=Builder↔Config)

Example:

cursus alignment validate-level currency_conversion 1 –verbose cursus alignment validate-level dummy_training 3

Usage

cursus alignment validate-level [OPTIONS] SCRIPT_NAME LEVEL

Options

--workspace-dirs <workspace_dirs>

Workspace directories to include in validation

-v, --verbose

Show detailed output

Arguments

SCRIPT_NAME

Required argument

LEVEL

Required argument

catalog

Step catalog management commands.

Usage

cursus catalog [OPTIONS] COMMAND [ARGS]...

component-info

Get detailed information about a specific component.

Usage

cursus catalog component-info [OPTIONS] STEP_NAME
                              {config|builder|contract|spec|script}

Options

--format <format>
Options:

text | json

--load

Load and inspect the actual class

Arguments

STEP_NAME

Required argument

COMPONENT_TYPE

Required argument

components

Show components available for a specific step.

Usage

cursus catalog components [OPTIONS] STEP_NAME

Options

--type <component_type>

Filter by component type (script, contract, spec, builder, config)

--format <format>

Output format

Options:

text | json

Arguments

STEP_NAME

Required argument

discover

Discover steps in a specific workspace directory.

Usage

cursus catalog discover [OPTIONS]

Options

--workspace-dir <workspace_dir>

Workspace directory to discover

--format <format>

Output format

Options:

text | json

fields

Show all configuration fields for a step.

Usage

cursus catalog fields [OPTIONS] STEP_NAME

Options

--inherited

Show inherited fields

--format <format>

Output format (‘table’ is a deprecated alias for ‘text’).

Options:

text | json | table

--show-types

Show field types

--show-defaults

Show default values

Arguments

STEP_NAME

Required argument

frameworks

List detected frameworks across all steps.

Usage

cursus catalog frameworks [OPTIONS]

Options

--format <format>

Output format (‘table’ is a deprecated alias for ‘text’).

Options:

text | json | table

list

List available steps with optional filtering.

Usage

cursus catalog list [OPTIONS]

Options

--workspace <workspace>

Filter by workspace ID

--job-type <job_type>

Filter by job type (e.g., training, validation)

--framework <framework>

Filter by detected framework

--format <format>

Output format (‘table’ is a deprecated alias for ‘text’).

Options:

text | json | table

--limit <limit>

Maximum number of results to show

list-builders

List all builder classes.

Usage

cursus catalog list-builders [OPTIONS]

Options

--step-type <step_type>

Filter by SageMaker step type

--framework <framework>

Filter by framework

--format <format>

Output format (‘table’ is a deprecated alias for ‘text’).

Options:

text | json | table

--show-path

Show file path

list-by-type

Filter steps by SageMaker step type.

Usage

cursus catalog list-by-type [OPTIONS] STEP_TYPE

Options

--framework <framework>

Filter by framework

--format <format>

Output format (‘table’ is a deprecated alias for ‘text’).

Options:

text | json | table

Arguments

STEP_TYPE

Required argument

list-configs

List all configuration classes.

Usage

cursus catalog list-configs [OPTIONS]

Options

--project-id <project_id>

Filter by project/workspace

--framework <framework>

Filter by framework

--format <format>

Output format (‘table’ is a deprecated alias for ‘text’).

Options:

text | json | table

--show-fields

Show field count for each config

list-contracts

List all contract classes.

Usage

cursus catalog list-contracts [OPTIONS]

Options

--with-scripts-only

Only show contracts with scripts

--format <format>

Output format (‘table’ is a deprecated alias for ‘text’).

Options:

text | json | table

--show-entry-points

Show script entry points

list-scripts

List all script files discovered.

Usage

cursus catalog list-scripts [OPTIONS]

Options

--project-id <project_id>

Filter by project/workspace

--format <format>

Output format (‘table’ is a deprecated alias for ‘text’).

Options:

text | json | table

--show-path

Show full file path

list-specs

List all specification classes.

Usage

cursus catalog list-specs [OPTIONS]

Options

--job-type <job_type>

Filter by job type

--framework <framework>

Filter by framework

--format <format>

Output format (‘table’ is a deprecated alias for ‘text’).

Options:

text | json | table

--show-dependencies

Show dependency count

metrics

Show step catalog performance metrics.

Usage

cursus catalog metrics [OPTIONS]

Options

--format <format>

Output format

Options:

text | json

search-field

Find steps with configs containing a specific field.

Usage

cursus catalog search-field [OPTIONS] FIELD_NAME

Options

--field-type <field_type>

Filter by field type (str, int, bool, dict, list)

--format <format>

Output format (‘table’ is a deprecated alias for ‘text’).

Options:

text | json | table

--show-default

Show default values

Arguments

FIELD_NAME

Required argument

show

Show detailed information about a specific step.

Usage

cursus catalog show [OPTIONS] STEP_NAME

Options

--format <format>

Output format

Options:

text | json

--show-components

Show detailed component information

Arguments

STEP_NAME

Required argument

workspaces

List available workspaces and their step counts.

Usage

cursus catalog workspaces [OPTIONS]

Options

--format <format>

Output format (‘table’ is a deprecated alias for ‘text’).

Options:

text | json | table

compile

Compile DAG and config JSON files to SageMaker Pipeline.

This command takes a serialized DAG JSON file and a configuration JSON file, then compiles them into a SageMaker Pipeline object. The pipeline can be saved to a file, deployed to SageMaker, and/or executed.

Examples:

# Basic compilation (console output only) cursus compile -d dag.json -c config.json

# Save pipeline definition to file cursus compile -d dag.json -c config.json -o pipeline_definition.json

# Deploy to SageMaker (upsert) cursus compile -d dag.json -c config.json –upsert

# Complete workflow (compile + upsert + start) cursus compile -d dag.json -c config.json –upsert –start

# Validation only cursus compile -d dag.json -c config.json –validate-only

# With detailed report cursus compile -d dag.json -c config.json –show-report

Usage

cursus compile [OPTIONS]

Options

-d, --dag-file <dag_file>

Required Path to serialized DAG JSON file

-c, --config-file <config_file>

Required Path to configuration JSON file

-n, --pipeline-name <pipeline_name>

Override pipeline name (optional)

--role <role>

IAM role ARN for pipeline execution (optional)

-o, --output <output>

Save pipeline definition to JSON file (optional)

--upsert

Create/update pipeline in SageMaker service

--start

Start pipeline execution after upserting (requires –upsert)

--format <format>

Output format for console display

Options:

text | json

--show-report

Display detailed compilation report

--validate-only

Only validate compatibility, don’t compile

config

Inspect the configuration a pipeline DAG requires.

Usage

cursus config [OPTIONS] COMMAND [ARGS]...

requirements

Show the configuration fields a DAG (or one of its steps) requires.

DAG_FILE: path to a serialized DAG JSON file.

Usage

cursus config requirements [OPTIONS] DAG_FILE

Options

--step <step_name>

Show requirements for one step only (default: base + all steps).

--format <format>

Output format.

Options:

text | json

Arguments

DAG_FILE

Required argument

dag

Inspect and validate pipeline DAG JSON files.

Usage

cursus dag [OPTIONS] COMMAND [ARGS]...

resolve

Score dependency-resolution edges among the named STEPS with the REAL resolver.

STEPS: two or more step names (e.g. a producer, a NEW step, a consumer). Each step’s interface is loaded from its .step.yaml, registered, and scored by the same UnifiedDependencyResolver (weights type .40 / data_type .20 / semantic .25 / exact-match .05 / source-compat .10 / keyword .05; threshold >= 0.5) the compiler runs.

For every dependency of every named step it reports the best-scoring provider among the other named steps, its score, and whether it resolves (>= 0.5). No score is computed by hand — this is the production resolver, so the author-time gate can trust the JSON.

Usage

cursus dag resolve [OPTIONS] STEPS...

Options

--format <format>

Output format.

Options:

text | json

Arguments

STEPS

Required argument(s)

validate

Validate the integrity of a serialized DAG JSON file.

DAG_FILE: path to a DAG JSON file (as produced by the serializer / compiler).

Reports cycles, dangling edges, isolated nodes, and nodes that do not resolve to a known step in the catalog. Exits nonzero if the DAG is invalid.

Usage

cursus dag validate [OPTIONS] DAG_FILE

Options

--format <format>

Output format.

Options:

text | json

Arguments

DAG_FILE

Required argument

exec-doc

Execution document generation commands.

Usage

cursus exec-doc [OPTIONS] COMMAND [ARGS]...

generate

Generate execution document from DAG and configuration files.

This command takes a serialized DAG JSON file and a configuration JSON file, then generates an execution document with step-specific configurations filled by specialized helpers (Cradle, Registration, etc.).

Examples:

# Basic usage cursus exec-doc generate -d dag.json -c config.json

# With custom output cursus exec-doc generate -d dag.json -c config.json -o my_exec_doc.json

# With template cursus exec-doc generate -d dag.json -c config.json –template base_template.json

# YAML output cursus exec-doc generate -d dag.json -c config.json –format yaml

# With IAM role cursus exec-doc generate -d dag.json -c config.json –role arn:aws:iam::123:role/MyRole

Usage

cursus exec-doc generate [OPTIONS]

Options

-d, --dag-file <dag_file>

Required Path to serialized DAG JSON file

-c, --config-file <config_file>

Required Path to configuration JSON file

-o, --output <output>

Output file path (default: execution_doc.json)

--template <template>

Base execution document template file (optional)

--format <format>

Output format (default: json)

Options:

json | yaml

--role <role>

IAM role ARN for AWS operations (optional)

--project-root <project_root>

Project folder used to anchor step source_dir resolution (the caller hook, Strategy 0). When omitted, inferred from the config file’s location.

--anchor-file <anchor_file>

A file inside the project folder (e.g. the template module); its parent directory is used as the project root. Alternative to –project-root.

-v, --verbose

Verbose output with detailed processing logs

mcp

Run and inspect the cursus MCP tool server.

Usage

cursus mcp [OPTIONS] COMMAND [ARGS]...

help

Print the guided overview of the cursus MCP toolset (the tools.help result).

Usage

cursus mcp help [OPTIONS]

Options

--namespace <namespace>

Restrict to one tool namespace (e.g. catalog, compile).

--phase <phase>

Restrict to one lifecycle phase.

Options:

planner | validator | programmer

--schema

Include each tool’s JSON input schema.

--examples

Show each tool’s usage examples (auto-on when –namespace is given).

--format <format>

Output format.

Options:

text | json

list-tools

List the tools registered in the cursus MCP registry.

Usage

cursus mcp list-tools [OPTIONS]

Options

--namespace <namespace>

Filter to one tool namespace (e.g. catalog, dag).

--format <format>

Output format.

Options:

text | json

serve

Run the cursus MCP server over stdio (requires the optional ‘mcp’ SDK).

Usage

cursus mcp serve [OPTIONS]

pipeline-catalog

Discover and recommend pre-built pipeline DAGs.

Usage

cursus pipeline-catalog [OPTIONS] COMMAND [ARGS]...

get-dag

Show nodes/edges and requirements for a catalog DAG by DAG_ID.

Usage

cursus pipeline-catalog get-dag [OPTIONS] DAG_ID

Options

--format <format>

Output format.

Options:

text | json

Arguments

DAG_ID

Required argument

list

List the frameworks available across the pipeline catalog.

Usage

cursus pipeline-catalog list [OPTIONS]

Options

--format <format>

Output format.

Options:

text | json

recommend

Recommend pre-built pipeline DAGs for your requirements.

Usage

cursus pipeline-catalog recommend [OPTIONS]

Options

--data-type <data_type>

Primary data type.

Options:

text | tabular | mixed

--has-labels, --no-labels

Labeled data already exists.

--needs-llm, --no-llm

LLM (Bedrock) needed.

--multi-task, --single-task

Multiple output tasks.

--incremental, --first-time

Incremental retraining.

--framework <framework>

Preferred ML framework.

Options:

pytorch | xgboost | lightgbm | lightgbmmt | any

--gpu, --no-gpu

GPU instances available.

--format <format>

Output format.

Options:

text | json

projects

Discover and inspect Cursus pipeline projects.

Usage

cursus projects [OPTIONS] COMMAND [ARGS]...

list

List pipeline projects under a root directory.

Scans each immediate subdirectory of –root and reports those that are recognizable Cursus pipeline projects (have a pipeline_config / pipeline_configs directory).

Usage

cursus projects list [OPTIONS]

Options

-r, --root <root>

Directory to scan for pipeline-project subdirectories.

--format <format>

Output format.

Options:

text | json

show

Show details for one pipeline project NAME (nodes, config types, modules).

With –root, looks for NAME under that directory; without –root, locates the uniquely-named project folder via cross-deployment generic discovery.

Usage

cursus projects show [OPTIONS] NAME

Options

-r, --root <root>

Directory containing the project (omit to locate it by name via generic search).

--format <format>

Output format.

Options:

text | json

Arguments

NAME

Required argument

registry

Registry management commands for hybrid registry system.

Usage

cursus registry [OPTIONS] COMMAND [ARGS]...

init-workspace

Initialize a new developer workspace with hybrid registry support.

Creates a complete workspace structure including: - Directory structure for custom step implementations - Local registry configuration - Documentation and usage examples - Integration with hybrid registry system

Args:

workspace_id: Unique identifier for the developer workspace workspace_path: Custom workspace path (optional) template: Registry template type (minimal/standard/advanced) force: Overwrite existing workspace

Usage

cursus registry init-workspace [OPTIONS] WORKSPACE_ID

Options

--workspace-path <workspace_path>

Custom workspace path (default: developer_workspaces/developers/{workspace_id})

--template <template>

Registry template to use

Options:

minimal | standard | advanced

--force

Overwrite existing workspace if it exists

Arguments

WORKSPACE_ID

Required argument

list-steps

List available steps in registry with optional workspace context.

Usage

cursus registry list-steps [OPTIONS]

Options

--workspace <workspace>

Workspace ID to list steps for

--conflicts-only

Show only conflicting steps

--include-source

Include source registry information

reset-validation-metrics

Reset validation performance metrics and cache.

Usage

cursus registry reset-validation-metrics [OPTIONS]

Options

--yes

Confirm the action without prompting.

resolve-step

Resolve a specific step name and show resolution details.

Usage

cursus registry resolve-step [OPTIONS] STEP_NAME

Options

--workspace <workspace>

Workspace context for resolution

--framework <framework>

Preferred framework for resolution

Arguments

STEP_NAME

Required argument

validate-registry

Validate registry configuration and check for issues.

Usage

cursus registry validate-registry [OPTIONS]

Options

--workspace <workspace>

Workspace ID to validate

--check-conflicts

Check for step name conflicts

validate-step-definition

Validate a step definition against standardization rules.

Usage

cursus registry validate-step-definition [OPTIONS]

Options

--name <name>

Required Step name to validate

--config-class <config_class>

Config class name (optional)

--builder-name <builder_name>

Builder class name (optional)

--sagemaker-type <sagemaker_type>

SageMaker step type (optional)

--auto-correct

Apply auto-correction to naming violations

--performance

Show performance metrics

validation-status

Show validation system status and performance metrics.

Usage

cursus registry validation-status [OPTIONS]

steps

Inspect step interfaces (I/O paths, property references, channels).

Usage

cursus steps [OPTIONS] COMMAND [ARGS]...

io

Show the I/O connection view for STEP_NAME: input/output container paths, the runtime property-path references, and the nested training channels.

Usage

cursus steps io [OPTIONS] STEP_NAME

Options

--job-type <job_type>

Resolve a job_type variant (training | validation | testing | calibration | …).

--format <format>

Output format.

Options:

text | json

Arguments

STEP_NAME

Required argument

patterns

Show the construction PATTERNS (the ‘plugins’) the TemplateStepBuilder uses for STEP_NAME: the bound create_step handler + the env / job-arg / input / output patterns, all derived from the step’s .step.yaml + registry binding. A ⚠ marks an axis the builder still hand-overrides.

Usage

cursus steps patterns [OPTIONS] STEP_NAME

Options

--job-type <job_type>

Resolve a job_type variant (training | validation | testing | calibration | …).

--format <format>

Output format.

Options:

text | json

Arguments

STEP_NAME

Required argument

strategies

Inspect the builder strategy library (axes, strategies, knobs).

Usage

cursus strategies [OPTIONS] COMMAND [ARGS]...

axes

List the routing axes and how many strategies each carries.

Usage

cursus strategies axes [OPTIONS]

Options

--format <format>

Output format.

Options:

text | json

for

Show the strategy the facade binds for a SAGEMAKER_STEP_TYPE (the authoring shortcut).

Usage

cursus strategies for [OPTIONS] SAGEMAKER_STEP_TYPE

Options

--step-assembly <step_assembly>

Processing sub-discriminator (code | step_args | delegation); default code.

--format <format>

Output format.

Options:

text | json

Arguments

SAGEMAKER_STEP_TYPE

Required argument

knobs

List the declarative knobs a strategy (–axis/–name) accepts.

Usage

cursus strategies knobs [OPTIONS]

Options

--axis <axis>

Required Routing axis of the strategy.

--name <name>

Required Strategy name on that axis.

--format <format>

Output format.

Options:

text | json

list

List registered strategies (optionally filtered by –axis).

Usage

cursus strategies list [OPTIONS]

Options

--axis <axis>

Filter to one routing axis.

--format <format>

Output format.

Options:

text | json

show

Show full detail for one strategy NAME (verb, handler, knobs, presets).

Usage

cursus strategies show [OPTIONS] NAME

Options

--axis <axis>

Disambiguate when a name exists on >1 axis.

--format <format>

Output format.

Options:

text | json

Arguments

NAME

Required argument

validate

Local pipeline-script testing and validation.

Usage

cursus validate [OPTIONS] COMMAND [ARGS]...

run-scripts

Execute a DAG’s pipeline scripts locally in dependency order.

DAG_FILE: path to a serialized DAG JSON file.

Runs each script with simulated data flow so you can verify the scripts work together before deploying to SageMaker. Exits nonzero if any script fails.

Usage

cursus validate run-scripts [OPTIONS] DAG_FILE

Options

-c, --config-file <config_file>

Required Path to the pipeline configuration JSON file.

--workspace-dir <workspace_dir>

Working directory for script execution artifacts.

Default:

'test/integration/script_testing'

--no-dependency-resolution

Disable automatic data-flow dependency resolution between scripts.

--format <format>

Output format.

Options:

text | json

Arguments

DAG_FILE

Required argument

step-interface

Validate a step’s .step.yaml interface at author time (FZ 31e1d3f2).

STEP_NAME: canonical step name (e.g. XGBoostTraining). Omit with –all to validate every step.

Loads the interface through the production StepInterface.from_yaml path — surfacing Pydantic field errors + the contract↔spec cross-section alignment check — then runs incompleteness checks (compatible_sources case-typos). Exits nonzero if any interface has a blocking error.

Usage

cursus validate step-interface [OPTIONS] [STEP_NAME]

Options

--job-type <job_type>

Resolve a job_type variant (e.g. validation).

--all

Validate every .step.yaml interface (CI).

--format <format>

Output format.

Options:

text | json

Arguments

STEP_NAME

Optional argument