kyber-cli 2.0.4

Kyber Developer Experience CLI — deploy agents in one command

Kyber CLI

Kyber CLI is a developer-experience command line for scaffolding, validating, running, and preparing AI agents for deployment. It gives you a small local project, managed runtime guardrails, structure validation, deterministic version pinning, and deploy-preview generation from one command surface.

Version: 2.0.0

Features

• Scaffold Python agent projects with generated config, circuit, manifest, tests, and runtime guardrails.
• Validate config schema, required project structure, managed runtime files, and Kyber CLI compatibility before execution.
• Run handlers or circuits locally through the Kyber-managed runtime wrapper.
• Preview expanded deploy manifests with platform defaults.
• Eject defaults for explicit customization.
• Pin the Kyber CLI version per repo or per machine.
• Print deterministic installer commands for exact CLI versions.

Installation

Development Install

git clone https://github.com/kyber/cli.git
cd cli
pip install -e .

Verify

kyber --version
kyber --help

Quick Start

kyber login
kyber design init invoice-parser --runtime python
cd invoice-parser
kyber design validate
kyber exec run circuit
kyber exec deploy --dry-run

Generated project layout:

invoice-parser/
|-- kyber.agent.json
|-- kyber.circuit.json
|-- manifest.json
|-- requirements.txt
|-- pytest.ini
|-- .kyber/
|   |-- runtime.lock.json
|   |-- runtime_wrapper.py
|   `-- direct_run_guard.py
|-- src/
|   `-- handler.py
`-- tests/
    |-- conftest.py
    |-- test_handler.py
    |-- test_circuit.py
    |-- test_guardrails.py
    `-- fixtures/
        `-- sample_event.json

Command Reference

Primary Commands

Command	Purpose	Example
kyber design init	Scaffold an agent project	kyber design init my-agent --runtime python
kyber design validate	Validate config, structure, runtime guardrails, and CLI compatibility	kyber design validate
kyber design test	Run the agent project's pytest test suite	kyber design test -v
kyber design explain	Show platform defaults and customization hints	kyber design explain --capability memory
kyber design eject	Export defaults for explicit customization	kyber design eject memory
kyber exec run	Run a handler or circuit through the managed runtime	kyber exec run circuit
kyber exec deploy	Preview or prepare deployment output	kyber exec deploy --dry-run
kyber exec status	Show local runtime/audit status	kyber exec status
kyber pin	Pin the Kyber CLI version per repo or machine	kyber pin --scope repo --version 2.0.0
kyber self-update	Print an exact installer command for a CLI version	kyber self-update --version 2.0.0 --manager pip
kyber compat	Show compatibility and pin precedence rules	kyber compat
kyber login	Authenticate to the platform	kyber login

Legacy aliases such as kyber init, kyber validate, kyber run, kyber status, kyber test, kyber deploy, kyber explain, and kyber eject remain callable for compatibility, but lifecycle groups are the preferred command surface.

Design Commands

kyber design init

Create a new agent project.

kyber design init my-agent
kyber design init support-bot --runtime python
kyber design init calendar-agent --runtime python --tools calendar --tools email

Options:

• --runtime: Agent runtime. Supported: python, node, go.
• --tools: Tool name to enable. Repeat the flag for multiple tools. --tool remains available as an alias.

kyber design validate

Validate the current project without a network call.

kyber design validate
kyber design validate --path ./agents/my-agent/kyber.agent.json
kyber design validate --verbose

Validation checks:

• kyber.agent.json syntax and schema version.
• Required generated files and directories are present and correctly placed.
• Python entrypoint lives under src/.
• Managed runtime wrapper, direct-run guard, and runtime lock are present and hash-valid.
• Runtime lock was generated by a compatible Kyber CLI major version.
• Active repo or machine pin matches the installed Kyber CLI exactly.

Example failure:

Validation failed
  - Required file missing or moved: requirements.txt. Restore the file at requirements.txt or rerun 'kyber design init <name>' and copy your changes into the generated layout.
  - Kyber DX 2.0.0 does not match the active repo pin 2.0.1 at .kyber/dx.json. Install the pinned version with 'kyber self-update --version 2.0.1' or update the pin with 'kyber pin --scope repo --version 2.0.0'.

kyber design test

Run the agent project's pytest test suite from the current agent project.

kyber design test
kyber design test -v
kyber design test -k handler
kyber design test --stop-on-first-failure

Options:

• --path, -p: Path to the test directory or a specific test file. Default: tests
• --verbose, -v: Verbose pytest output.
• --coverage, -c: Generate coverage report (requires pytest-cov).
• --markers, -m: Run pytest markers using -m.
• --keyword, -k: Run pytest keyword expressions using -k.
• --stop-on-first-failure, -x: Stop execution when the first test fails.
• --show-locals, -l: Show local variables in tracebacks.

kyber design explain

Inspect platform defaults and how to override them.

kyber design explain --capability memory

Total time: < 5 minutes ⚡

---

📚 Command Reference

Core Commands

Command	Purpose	Example
kyber init	Create new agent project	kyber init my-agent --runtime python
kyber validate	Check config syntax & schema	kyber validate
kyber test	Run the project's pytest suite	kyber test -v
kyber deploy	Deploy to environment	kyber deploy --env prod
kyber run	Run a handler or circuit locally	kyber run circuit
kyber status	Show local runtime/audit status	kyber status
kyber explain	Show applied defaults	kyber explain --capability memory
kyber eject	Export config for customization	kyber eject memory
kyber pin	Pin CLI version per repo or machine	kyber pin --scope repo --version 2.0.0
kyber self-update	Print deterministic installer command	kyber self-update --version 2.0.0 --manager pip
kyber compat	Show CLI/runtime compatibility metadata	kyber compat --json
kyber login	Authenticate to platform	kyber login

Detailed Usage

kyber compat - Show CLI Compatibility Metadata

Expose the installed Kyber CLI version and the supported runtime lock version range.

kyber compat

# Machine-readable
kyber compat --json

kyber compat --json exposes:

{
  "dx_version": "2.0.0",
  "supported_runtime_version_range": "2.x.x"
}

Runtime locks generated by the same Kyber CLI major version are compatible. Execution is blocked when the active repo/machine pin does not match the installed CLI.

---

kyber init — Scaffold New Agent

Create a minimal agent project with Tier 1 configuration (4 fields only).

kyber design eject memory
kyber design eject governance
kyber design eject identity
kyber design eject all

Typical customization flow:

kyber design eject memory
notepad kyber.memory.yaml
kyber exec deploy --dry-run

Execution Commands

kyber exec run

Run a handler or circuit through the Kyber-managed runtime. Execution is blocked if validation, structure, runtime guardrail, or CLI compatibility checks fail.

kyber exec run
kyber exec run circuit
kyber exec run --event '{"input": "hello"}'
kyber exec run --event-file tests/fixtures/sample_event.json
kyber exec run circuit --circuit-file kyber.circuit.json

Options:

• --event, -e: Inline JSON event payload.
• --event-file, -f: Path to a JSON event file.
• --circuit-file: Circuit JSON file used when running circuit.

kyber exec deploy

Expand config with platform defaults and preview or prepare deployment output.

kyber exec deploy --dry-run
kyber exec deploy --env dev
kyber exec deploy --env stage
kyber exec deploy --env prod

Options:

• --env: Target environment. Supported: dev, stage, prod. Default: dev.
• --dry-run: Print expanded config and generated manifest without deploying.
• --manifest-path: Output path for the generated manifest. Default: manifest.json.

kyber exec status

Show local runtime/audit state.

kyber exec status
kyber exec status --path .
kyber exec status --limit 20

Versioning Commands

Kyber supports deterministic CLI versioning. Pins are explicit, installer commands use exact versions, and execution is blocked when the active pin or runtime lock is incompatible.

kyber pin

Pin the Kyber CLI version for the current repo or the current machine.

kyber pin --scope repo --version 2.0.0
kyber pin --scope machine --version 2.0.0

Pin files:

• Repo pin: .kyber/dx.json
• Machine pin on Windows: C:\Users\<you>\AppData\Local\kyber\dx.json
• Machine pin on Linux/macOS: ~/.kyber/dx.json

Precedence:

1. Repo pin wins when .kyber/dx.json exists.
2. Machine pin is used when no repo pin exists.
3. No pin means the installed CLI is accepted, subject to runtime lock compatibility.

kyber self-update

Print a deterministic installer command for an exact Kyber CLI version. This command intentionally avoids floating latest installs.

kyber self-update --version 2.0.0 --manager pip
kyber self-update --version 2.0.0 --manager pipx
kyber self-update

If --version is omitted, Kyber uses the active pin when present, otherwise the currently installed CLI version.

kyber compat

Show compatibility and pin precedence rules.

kyber compat

Policy summary:

• Runtime locks generated by the same Kyber CLI major version are compatible.
• Future or different-major runtime locks block execution.
• Repo pins override machine pins.
• Active pins must exactly match the installed Kyber CLI version.

Authentication

kyber login
kyber login --env stage
kyber login --no-browser

Options:

• --env: Target environment. Supported: dev, stage, prod. Default: prod.
• --no-browser: Print auth URL instead of opening a browser.

Token storage on Windows: C:\Users\<you>\AppData\Local\kyber\config.json

Configuration

Minimum generated config lives in kyber.agent.json:

{
  "schema_version": "4.5.7",
  "name": "invoice-parser",
  "runtime": "python",
  "tools": [],
  "entrypoint": "src/handler.py",
  "profile": "standard"
}

The defaults engine expands this into a full manifest for deployment previews. Developer-provided config wins over defaults.

Typical Workflow

kyber design init invoice-parser --runtime python
cd invoice-parser

notepad src/handler.py

kyber design validate
kyber exec run circuit
kyber design explain --capability memory
kyber exec deploy --dry-run

kyber design eject memory
notepad kyber.memory.yaml
kyber exec deploy --dry-run

Development

Run tests:

.\venv\Scripts\python.exe -m pytest

Validation checklist:

kyber --version
kyber --help

kyber design init test-agent --runtime python
cd test-agent

kyber design validate
kyber exec run circuit
kyber design explain --capability memory
kyber design eject memory
kyber exec deploy --dry-run

kyber pin --scope repo --version 2.0.0
kyber compat
kyber self-update --version 2.0.0 --manager pip

Current Limitations

Feature	Status
Real deployments	--dry-run and manifest generation are available; control-plane integration is pending.
OIDC authentication	Stub implementation for local development.
Container registry push	Not implemented yet.
Usage telemetry	Disabled.

Support

• Documentation: https://kyber.ai/docs
• Issues: https://github.com/kyber/cli/issues
• Email: [e-mail]

Roadmap

• Control Plane API integration for real deployments.
• Production OIDC authentication flow.
• Container registry integration.
• Interactive config builder.
• Real-time deployment logs.

License

This project is licensed under the MIT License.