Kostral
CLI Reference

Copy. Paste. Run.

A command-oriented reference for developers and contributors. The installed CLI remains authoritative; use koss <command> --help for the exact interface in your version.

Install

Install from PyPI, then check the CLI with koss --help.

pip install kostral
# or keep it isolated from your project environments:
pipx install kostral

Synopsis

koss <command> [arguments] [options]

koss --help
koss <command> --help

Commands

CommandPurposeExample
koss explainAnalyze a Kubernetes manifest with Validator and Security.koss explain ./app.yaml
koss optimizeOptimize the input state, then analyze the resulting state.koss optimize ./app.yaml
koss remoteRun a user-defined workflow whose engines can be invoked through remote HTTP clients (experimental).koss remote ./app.yaml --exec ./workflow.py
koss runRun a Kostral workflow from a Python DSL input.koss run ./examples/dsl/app.py
koss generateProvide deployment input through CLI parameters.koss generate --name backend --cpu 500m --memory 512Mi --image nginx:1.27 --target local

Explain

Use this when you want analysis only, without running the Optimizer.

koss explain ./examples/demo/bad.yaml
koss explain ./examples/demo/bad.yaml --output=json
koss explain ./examples/demo/bad.yaml --output=yaml
koss explain ./examples/demo/bad.yaml --output=yaml --verbose

Optimize

Use this when you want the optimization workflow followed by the relevant analysis.

koss optimize ./examples/demo/bad.yaml
koss optimize ./examples/demo/bad.yaml --output=json
koss optimize ./examples/demo/bad.yaml --output=yaml
koss optimize ./examples/demo/bad.yaml --output=yaml --verbose
koss optimize ./examples/demo/bad.yaml --dry-run
Experimental

Remote

Run a user-defined workflow whose engines are invoked through remote HTTP clients. Start the three engine servers first, each in its own terminal and from the repository root.

terminals 1–3 · start the engines
python examples/remote/optimizer_server.py   # http://127.0.0.1:9001/process
python examples/remote/validator_server.py   # http://127.0.0.1:9002/process
python examples/remote/security_server.py    # http://127.0.0.1:9003/process
terminal 4 · run the workflow
koss remote ./examples/demo/bad.yaml \
  --exec ./examples/remote/workflow.py

koss remote ./examples/demo/bad.yaml --exec ./examples/remote/workflow.py --output=json
koss remote ./examples/demo/bad.yaml --exec ./examples/remote/workflow.py --output=yaml
koss remote ./examples/demo/bad.yaml --exec ./examples/remote/workflow.py --verbose
Demonstration, not a platform: engines are located through a static examples/remote/registry.json and local HTTP endpoints. Run from the repository root, because the example workflow opens the registry by relative path. There is no dynamic discovery, authentication, TLS, or parallel remote execution yet. See docs/remote-engines.md.

Python DSL

The DSL is entered directly through its Python file.

project
examples/
└── dsl/
    └── app.py

$ koss run ./examples/dsl/app.py
Input: app.py is the Python DSL entry point for koss run.
Python DSL

koss run + examples/dsl/app.py

The repository includes a Python DSL example that defines a deployment and a PVC.

examples/dsl/app.py
from kostral.dsl import deployment, pvc

api = deployment(
    "nginxdsl-dep",
    cpu="80m",
    memory="9Mi",
    image="nginx:latest",
    replicas=2,
    ports=[5000],
)

pvc(
    name="mongo-dsl-pvc",
    storage="5Gi",
    storage_class="standard",
)
run
koss run ./examples/dsl/app.py
Secondary / on hold: koss run is documented for the DSL path but is not the primary CLI workflow.

Generate

Use CLI parameters to provide deployment input to Kostral.

koss generate \
  --name backend \
  --cpu 500m \
  --memory 512Mi \
  --image nginx:1.27 \
  --target local
Secondary / on hold: koss generate is the CLI-based deployment input path and may be reintroduced later.

Output

OptionUse
--output=jsonMachine-readable report/output.
--output=yamlYAML manifest output.
--verboseAdditional reporting/diagnostics.

When YAML is the selected output, the YAML stream should remain suitable for piping or saving as a manifest. Verbose diagnostics may be separated from that stream by the CLI implementation.

Common copy/paste patterns

# inspect
koss explain ./app.yaml

# machine-readable report
koss explain ./app.yaml --output=json

# optimize
koss optimize ./app.yaml

# save optimized YAML
koss optimize ./app.yaml --output=yaml > optimized.yaml

# save YAML while requesting verbose diagnostics
koss optimize ./app.yaml --output=yaml --verbose > optimized.yaml

# run a remote-engine workflow (engine servers must be running)
koss remote ./app.yaml --exec ./examples/remote/workflow.py

# inspect command-specific options
koss optimize --help

Full reference

The repository version of this page is docs/usage.md. Keep it synchronized with the actual CLI implementation.

Open usage.md on GitHub Remote engines guide
Secondary / on hold: koss run is the Python DSL workflow entry point and koss generate is the CLI-based deployment input path. Both are currently on hold and may be reintroduced later.