Metadata-Version: 2.4
Name: kyber-cli
Version: 2.0.8
Summary: Kyber Developer Experience CLI — deploy agents in one command
Author-email: Symplii <hello@symplii.ai>
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"
Requires-Dist: pytest-cov>=4.0.0
Requires-Dist: pytest>=7.0.0
Provides-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 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 workflow` |
| `kyber design explain defaults` | Inspect versioned defaults profile values | `kyber design explain defaults --profile standard --key identity.client_id` |
| `kyber design eject` | Export manifest section defaults for customization | `kyber design eject workflow` |
| `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 tools` | List active tools from the Tool Gateway registry | `kyber tools` |
| `kyber tools --tool` | Show one registered tool's invocation contract | `kyber tools --tool weather-api` |
| `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.

### Tool Gateway registry

Browse the tools currently available through the Kyber Tool Gateway:

```bash
kyber tools
kyber tools --tool weather-api
```

Both commands also accept `--json` for machine-readable output. The local gateway
endpoint defaults to `http://127.0.0.1:8000`. Configure authentication and, when
needed, override the endpoint with environment variables:

```bash
KYBER_TOOL_GATEWAY_SHARED_SECRET=<platform-shared-secret>
KYBER_TOOL_GATEWAY_BASE_URL=http://127.0.0.1:8000
```

The same values can be stored under `tool_gateway.shared_secret` and
`tool_gateway.base_url` in the Kyber machine `config.json`.

Tool registry responses are cached for 30 minutes in the CLI-managed machine
cache at `cache/tool-registry.json` under the Kyber config directory (for example,
`%LOCALAPPDATA%\kyber\cache\tool-registry.json` on Windows). `kyber tools`, tool
detail lookup, and `kyber design validate` share this cache. A missing, invalid, or
expired cache is refreshed from the Tool Gateway API. Authentication secrets are
never written to the cache.

Declared tools require explicit least-privilege permissions. `kyber validate`
checks each permission against the tool's cached `supported_operations`. For
example, if `manual-vendor-pricing-api` supports `query`:

```json
{
  "tools": ["manual-vendor-pricing-api"],
  "integrations": {
    "data_access": [
      {
        "source": "manual-vendor-pricing-api",
        "permissions": ["query"]
      }
    ],
    "external_apis": ["manual-vendor-pricing-api"]
  }
}
```

## 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 --tools calendar --tools email
```

Options:

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

### `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 config fields: `schema_version`, `name`, `runtime`, `tools`, and `entrypoint`.
  `version` defaults to `1.0.0` when omitted.
- 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 test`

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

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

```powershell
kyber design explain --capability workflow
kyber design explain defaults
kyber design explain defaults --profile standard
kyber design explain defaults --profile regulated --key cost_and_telemetry.telemetry_intent
kyber design explain defaults --profile high-volume --json
```

Use `kyber design explain` without a topic from inside an agent project to see the defaults that are applied to that agent after tier/profile detection. Use the `defaults` topic to inspect the versioned defaults registry directly, even when you only want one dotted key.

Options for `kyber design explain defaults`:

- `--profile`: Defaults profile to inspect. Supported profiles are `minimal`, `standard`, `regulated`, and `high-volume`. Default: `standard`.
- `--version`: Defaults profile version to inspect. When omitted, Kyber uses the current version for the selected profile.
- `--key`: Dotted defaults path to show, such as `identity.client_id`, `workflow.execution_mode`, or `memory_capabilities.scope_access`.
- `--json`: Print machine-readable JSON output.

### Team Custom Profiles

Teams can share custom defaults profiles by committing `kyber.profiles.json` at the agent project root. Custom profile names use lowercase letters, numbers, and hyphens, and can extend a built-in profile while overriding only selected dotted defaults.

```json
{
  "profiles": {
    "team-secure": {
      "extends": "regulated",
      "metadata": {
        "name": "Team Secure",
        "description": "Team security baseline",
        "tier": 2
      },
      "versions": {
        "1.0": {
          "defaults": {
            "deployment_metadata.profile": "team-secure",
            "cost_and_telemetry.max_cost_usd": 25,
            "cost_and_telemetry.telemetry_intent": ["logs", "events"]
          }
        }
      }
    }
  }
}
```

Then select it from `kyber.agent.json`:

```json
{
  "profile": "team-secure"
}
```

### Defaults Commands

Kyber has a versioned defaults registry for platform-managed manifest sections. The public agent workflow normally uses:

```powershell
kyber design explain defaults
kyber explain defaults
kyber design explain defaults --profile standard --key identity.client_id
kyber exec deploy --dry-run
```

`kyber design explain defaults` is the preferred lifecycle command. `kyber explain defaults` remains available as a compatibility alias.

Some builds or internal/platform tooling may also expose the lower-level `kyber defaults` command group. It contains:

```powershell
kyber defaults explain --profile standard
kyber defaults explain --profile standard --version 1.0
kyber defaults explain --profile regulated --key cost_and_telemetry.telemetry_intent
kyber defaults explain --profile high-volume --json

kyber defaults migrate --profile standard --from 1.0 --to 1.0
kyber defaults migrate --agent agent-1@default:1.0.0
kyber defaults migrate --agent agent-1@default:1.0.0 --accept-breaking
kyber defaults migrate --profile regulated --from 1.0 --to 1.0 --json

kyber defaults pin --agent agent-1@default:1.0.0 --profile standard
kyber defaults pin --agent agent-1@default:1.0.0 --profile standard --version 1.0
kyber defaults pin --agent agent-1@default:1.0.0 --profile standard --json
```

Command behavior:

- `kyber defaults explain`: Shows defaults metadata and values for a profile/version. Use `--key` to inspect one dotted path, or `--json` for machine-readable output.
- `kyber defaults migrate`: Shows changes between defaults versions. Use `--agent` to read that agent's existing defaults pin, or provide `--profile` and `--from` manually. Breaking changes require `--accept-breaking` before an agent pin is updated.
- `kyber defaults pin`: Writes or updates the local defaults pin for an agent. Deploy also writes a defaults pin automatically after preparing a local MVP deployment handoff.

Options:

- `kyber defaults explain`: `--profile`, `--version`, `--key`, `--json`.
- `kyber defaults migrate`: `--profile`, `--from`, `--to`, `--agent`, `--accept-breaking`, `--json`.
- `kyber defaults pin`: `--agent`, `--profile`, `--version`, `--json`.

Defaults pins are stored under `.kyber/deployments/` and record the agent id, defaults profile, defaults version, platform release, and update timestamp. They are local audit metadata; they do not call real services.

**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 workflow` |
| `kyber eject` | Export manifest section config for customization | `kyber eject workflow` |
| `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 a compact configuration.

```powershell
kyber design eject workflow
kyber design eject identity
kyber design eject intelligence
kyber design eject all
```

Typical customization flow:

```powershell
kyber design eject workflow
notepad workflow.json
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 authored config lives in `kyber.agent.json`:

```json
{
  "schema_version": "v1",
  "name": "invoice-parser",
  "runtime": "python",
  "tools": [],
  "entrypoint": "src/handler.py"
}
```

The config schema version (`schema_version`) describes the shape of `kyber.agent.json`; keep it explicit so future schema versions can be selected intentionally. The agent version (`version`) defaults to `1.0.0` unless you set your own semantic version. The defaults engine expands this into a full manifest for deployment previews. Developer-provided config wins over defaults.

Optional authored sections are `capability`, `configuration`, `integrations`, `cost_and_telemetry`, `memory_capabilities`, `memory`, `governance`, `orchestration`, `identity`, `gateway`, `governed_objects`, `lifecycle`, `commercial`, `intelligence`, and `policy_engine`. Authored config is validated by Kyber's config model; generated deploy manifest JSON Schemas are published as `kyber/core/schemas/kyber.manifest.vN.schema.json`.

The config `schema_version` selects the manifest schema major version generically: `vN` uses manifest schema `N.0.0` and `kyber/core/schemas/kyber.manifest.vN.schema.json`. To add `v3`, `v4`, `v5`, or later, add the matching schema file. To make that schema the default for newly initialized projects, update `AGENT_CONFIG_SCHEMA_VERSION` in `kyber/core/schema_version.py`.

Use `kyber design eject <section>` to customize defaulted sections without adding them to `kyber.agent.json`. For example, `kyber design eject workflow` creates `workflow.json`; edits to that file are merged into the generated `manifest.json` on deploy.

## 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 workflow
kyber exec deploy --dry-run

kyber design eject workflow
notepad workflow.json
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 workflow
kyber design eject workflow
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.

