Metadata-Version: 2.4
Name: kyber-cli
Version: 2.0.1
Summary: Kyber Developer Experience CLI — deploy agents in one command
Author-email: Your Name <uzma.techtimize@gmail.com>
License: Apache-2.0
Keywords: kyber,agent,cli,deployment
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyfiglet>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: jsonschema>=4.17.0
Requires-Dist: pywin32>=305; sys_platform == "win32"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"

# 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

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

### Verify

```powershell
kyber --version
kyber --help
```

## Quick Start

```powershell
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:

```text
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 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`, and `kyber deploy` remain callable for compatibility, but lifecycle groups are the preferred command surface.

## Design Commands

### `kyber design init`

Create a new agent project.

```powershell
kyber design init my-agent
kyber design init support-bot --runtime python
kyber design init calendar-agent --runtime python --tool calendar --tool email
```

Options:

- `--runtime`: Agent runtime. Supported: `python`, `node`, `go`.
- `--tool`: Tool name to enable. Repeat the flag for multiple tools.

### `kyber design validate`

Validate the current project without a network call.

```powershell
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:

```text
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 explain`

Inspect platform defaults and how to override them.

```powershell
kyber deploy --env dev
# Agent deployed and ready to handle requests
```

**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 deploy` | Deploy to environment | `kyber deploy --env prod` |
| `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.

```powershell
kyber compat

# Machine-readable
kyber compat --json
```

`kyber compat --json` exposes:

```json
{
  "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).

```powershell
kyber design eject memory
kyber design eject governance
kyber design eject identity
kyber design eject all
```

Typical customization flow:

```powershell
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.

```powershell
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.

```powershell
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.

```powershell
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.

```powershell
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.

```powershell
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.

```powershell
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

```powershell
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`:

```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

```powershell
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:

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

Validation checklist:

```powershell
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: support@kyber.ai

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

