Command-line interface

Sygaldry ships a sygaldry CLI for loading config, building objects, and calling methods directly from the terminal. It is built on Click with Rich-styled help output.

Commands

sygaldry run (default): Load config, resolve an object, and call it.
sygaldry show: Display the merged config for debugging.
sygaldry validate: Validate config without executing anything.
sygaldry check: Static type check a config file.
sygaldry interactive: Start an interactive Python session with the config loaded.

When no subcommand is given, run is assumed.

run

sygaldry run -c CONFIG [--object KEY] [--set K=V] [--use K=K]
             [--method NAME] [--dry-run] [-v] [-q] [-- ARG ...]

Options

-c / --config (required, repeatable)

Path to a YAML or TOML config file. When repeated, files are deep-merged left to right so later files override earlier ones.

Can also be set via the SYGALDRY_CONFIG environment variable.

--object (required)

Top-level config key to resolve and use.

--set (repeatable)

Override a config value before interpolation: dotted.path=value. Values are automatically coerced (42 becomes an int, true a bool, null becomes None).

--use (repeatable)

Copy a value from one config path to another before interpolation: target.path=source.path. Useful for swapping defaults.

--method

Method to call on the resolved object. If omitted, the object itself is called (__call__). Can also be set via _call in config.

--dry-run

Validate config and display what would be called, without executing.

-v / --verbose

Show full tracebacks on error.

-q / --quiet

Suppress non-error output.

-- ARG ...

Positional arguments passed to the called method, separated from options by --. Values are type-coerced the same way as --set.

Return value handling

If the method returns an int, it becomes the process exit code.
If the method returns a non-None, non-int value, it is printed to stdout (unless -q).

Examples

# Basic: resolve an object and call it
sygaldry -c config.yaml --object pipeline

# Multiple configs, deep-merged left to right
sygaldry -c base.yaml -c prod.yaml --object pipeline

# Override a nested value
sygaldry -c config.yaml --object pipeline --set db.host=prod-db

# Swap a value for another config path
sygaldry -c config.yaml --object pipeline --use db.host=defaults.prod_host

# Call a specific method with arguments
sygaldry run -c config.yaml --object pipeline --method process -- 42 hello true

# Dry run
sygaldry run -c config.yaml --object pipeline --dry-run

show

sygaldry show -c CONFIG [--set K=V] [--use K=K] [--object KEY]
              [--format yaml|json] [--resolved] [--list-objects]

Options

--object: Show only this top-level key instead of the full config.
--format (yaml or json, default: yaml): Output format. Use json for piping to jq or other tools.
--resolved: Show the post-resolution config (objects instantiated, shown via repr).
--list-objects: List available top-level config keys.

Examples

# Pretty-print merged config
sygaldry show -c base.yaml -c prod.yaml

# Show a single object's config as JSON
sygaldry show -c config.yaml --object db --format json

# List available objects
sygaldry show -c config.yaml --list-objects

validate

sygaldry validate -c CONFIG [--set K=V] [--use K=K]

Loads, merges, interpolates, and resolves the full config. Prints a success message if valid, or an error with context if not. Useful for CI pipelines.

sygaldry validate -c config.yaml

check

sygaldry check -c CONFIG [--set K=V] [--use K=K]
               [--type-checker ty|basedpyright|pyright|mypy] [-v]

Generates equivalent Python source from the loaded config and runs a static type checker on it. This catches wrong argument names, wrong argument types, and type mismatches in _ref wiring without instantiating any objects.

Options

--type-checker (ty, basedpyright, pyright, or mypy): Which type checker to use. When omitted the first available checker is selected, preferring ty then basedpyright then pyright then mypy. See Type Checking for details.
-v / --verbose: Show full tracebacks on error.

How it works

The config is loaded, merged, and interpolated as usual.
For each _type entry, the checker generates a Python constructor call with the same arguments that would be passed at runtime.
_ref entries become variable references so the type checker can verify that the referenced object is compatible with the target parameter.
The generated source is written to a temporary file and passed to the selected type checker.
Errors are mapped back to config paths and printed.

Examples

# Auto-detect the type checker
sygaldry check -c config.yaml

# Use a specific checker
sygaldry check -c config.yaml --type-checker pyright

# Multiple configs with overrides
sygaldry check -c base.yaml -c prod.yaml --set db.host=prod-db

interactive

sygaldry interactive -c CONFIG [--set K=V] [--use K=K] [-v]

Loads and merges the config, then drops into an interactive Python REPL with the Artificery instance ready to use. This is useful for exploring a config, inspecting resolved objects, or experimenting with the object graph.

Options

-v / --verbose: Show full tracebacks on error.

Available variables

artificery: The Artificery instance with config loaded and merged.
Artificery: The Artificery class itself.

Examples

# Start a session with a single config
sygaldry interactive -c config.yaml

# Merge multiple configs and override a value
sygaldry interactive -c base.yaml -c dev.yaml --set db.host=localhost

Inside the REPL:

>>> artificery.config                # view the interpolated config
>>> artificery.resolve()             # resolve all objects
>>> obj = artificery.resolve("db")   # resolve a single object

The `_call` key

You can set default method and argument values in the config file itself using the _call reserved key. This avoids having to pass --method and arguments on every invocation.

pipeline:
  _type: "myapp.Pipeline"
  _call:
    method: "execute"
    args:
      - "daily"
  db: { _ref: "db" }

With this config:

# Calls pipeline.execute("daily")
sygaldry -c config.yaml --object pipeline

# Override method: calls pipeline.run("daily")
sygaldry -c config.yaml --object pipeline --method run

# Override args: calls pipeline.execute(100, "weekly")
sygaldry -c config.yaml --object pipeline -- 100 weekly

CLI --method overrides _call.method. Arguments after -- override _call.args.

Override and substitution order

The CLI processes config in this order:

Load each -c file (with _include expansion).
Deep-merge files left to right.
Apply --use substitutions (copies raw values within the config).
Apply --set overrides (explicit values win last).
Interpolate ${...} placeholders.
Extract _call defaults for the target object.
Resolve component definitions into live objects.
Call the selected method with the final arguments.

Because --set and --use are applied before interpolation, any ${...} references elsewhere in the config will pick up the overridden values.

Command-line interface

Commands

run

Options

Return value handling

Examples

show

Options

Examples

validate

check

Options

How it works

Examples

interactive

Options

Available variables

Examples

The _call key

Override and substitution order

The `_call` key