@kadi.build/cli

v0.0.1-alpha.12

Published

7 months ago

A CLI for interacting with the Knowledge and Ability Deployment Interface (KADI), an agent management system for managing installation of agents and abilities in distributed environments.

Downloads

0High
0Medium
0Low

coreyclarkphd

kassi-bertrand

KADI CLI – Knowledge & Ability Deployment Interface

KADI CLI – Knowledge & Ability Deployment Interface

What is KADI?

KADI (Knowledge & Ability Deployment Interface) is a modular tool-chain for building, packaging, and running software agents.
It ships as a very small CLI that speaks just one language:

kadi <command> [...options]

…but it becomes powerful by loading every command from a plugin at run-time.
Each plugin is a normal Node.js module living inside the abilities/ folder (for now).

Key Concepts

Agents

A KADI agent is a self-contained directory that implements some behavior – AI assistant, micro-service, data pipeline, you name it.
The only contract is the presence of an agent.json manifest at the root.

Abilities

An ability is to an agent what a package is to an operating system: a self-contained, reusable piece of functionality.
Each ability is stored under abilities/<name>/<version>/ and ships its own agent.json manifest.

Typical use cases:

Provide a domain-specific tool the KADI broker can invoke (e.g. text-to-speech, PDF parsing).
Bundle data or models an agent can access locally.
Extend the CLI itself (see next section).

Example – adding outbound phone calls to an agent:

# inside your agent folder
kadi install phone

The phone ability (and its dependencies) are downloaded, placed under abilities/phone/<version>/, and immediately available for use.

CLI Plugins

A CLI plugin stands in the same relationship to the KADI binary as an ability does to an agent: it augments behaviour without altering the host code-base.
To be recognized, a plugin must export a default JavaScript function with the signature:

import { IKadiContext } from 'kadi'; // types only
export default function myPlugin(ctx: IKadiContext) {
  /* … */
}

CLI plugins only affect the global CLI. Placing them in an agent directory has no effect – they must be installed via the command below so the CLI can locate them:

# install a plugin and its dependencies
kadi install <plugin-name>

Manual copying or npm install is not supported. The CLI resolves versions, installs to its own abilities/ tree, and updates the root agent.json automatically.

At start-up the KADI binary inspects the first positional argument (install, run, deploy, …) and lazy-loads the matching plugin. If the plugin registers a Commander command of the same name the user never notices the indirection.

Getting Started

Prerequisites

Node.js 18 or newer
podman

Installation

The recommended way to install KADI is via npm:

# Install globally (Node ≥ 18)
npm install -g @kadi.build/cli

Uninstallation

To remove KADI from your system:

# Uninstall the CLI
npm uninstall -g @kadi.build/cli

Create Your First Agent

Now create your first agent in a new directory:

# 1. Bootstrap a new agent
kadi init  # Creates a new agent with interactive setup

# 2. Install the abilities declared in agent.json
kadi install

# 3. Start the agent
kadi run        # executes the "start" lifecycle script

For Contributors & Maintainers

If you're working on the KADI CLI itself or need the development environment, you can use the experimental installers:

Quick install (Linux & macOS)

# download the installer
curl -o install_kadi.sh http://kadi.build/uploads/install_kadi_linux.sh

# make it executable and run it
chmod +x install_kadi.sh
./install_kadi_exp.sh

The script drops the kadi binary on your PATH and optionally starts a local kadi-server for offline experimentation.

Quick install (Windows)

# download the installer
Invoke-WebRequest -Uri https://agents.hewmen.ai/uploads/install_kadi_win.ps1 -OutFile install_kadi_win.ps1

# run it
.\install_kadi_win.ps1

If PowerShell blocks the script, either run it as Administrator or temporarily allow local scripts:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Tip: Both installers configure the CLI and a local kadi-server for offline testing.

`agent.json` – the manifest

agent.json plays the same role package.json plays in npm: single source of truth.
Below is the current canonical example – copy & modify.

{
  "name": "agentA",
  "version": "1.0.0",
  "license": "MIT",
  "description": "Mock KADI Agent A demonstrating tool registration and cross-agent invocation.",
  "repo": "",
  "lib": "",
  "brokers": {
    "local": "ws://127.0.0.1:8080",
    "remote": "ws://146.190.121.213:8080"
  },
  "abilities": {},
  "scripts": {
    "preflight": "",
    "setup": "npm install",
    "start": "node agentA.js",
    "stop": ""
  },
  "deploy": {
    "services": {
      "agenta": {
        "image": "kassibert/agent-a:build-4",
        "ports": ["8080:8080"],
        "stdin_open": true,
        "tty": true,
        "networks": ["net"]
      }
    },
    "networks": { "net": {} }
  }
}

Lifecycle Scripts

KADI agents use lifecycle scripts to define their behavior at different stages of their existence.

Script Execution Order

When you run kadi run, the following scripts execute in sequence:

preflight (optional) - Runs before anything else
setup (required) - Install dependencies, create configs, initialize data
start (required) - Launch the agent's main process
stop (optional) - Gracefully shut down, close connections, clean up

Additional scripts like restart, healthcheck, bundle, etc. can be added as needed.

Required vs Optional Scripts

| Script | Required | Purpose | When Executed | | ----------- | -------- | --------------------------------------------------------------------- | ------------------- | | preflight | no | Validate environment, download assets – runs before anything else | kadi run (first) | | setup | yes | Install dependencies, create configs, initialize data | kadi run (second) | | start | yes | Launch the agent's main process | kadi run (third) | | stop | no | Gracefully shut down, close connections, clean up | kadi stop |

setup and start are hard requirements – KADI will refuse to deploy an agent without them.

Best Practices

Don't exit with non-zero codes unless you really mean it - If the failure is minor or only prevents optional features, print a warning and exit successfully
Use setup for one-time initialization - Install dependencies, create configuration files, download models
Use start for the main process - Launch your agent's primary service, web server, or background process
Use stop for graceful shutdown - Close database connections, save state, terminate child processes
Use preflight for validation - Check environment variables, verify external services are available
Don't prefix commands with "sudo" - If root permissions are required, let the user run the command with sudo

The Plugin Architecture

How command resolution works

User types kadi <command> (e.g. kadi deploy).
The CLI looks into its own agent.json.cliPlugins map first – this allows explicit overrides.
If nothing matches it falls back to abilities/<command>/<latest>/index.js.
The file is imported as an ES module and its default export is executed with the shared context.

See src/index.ts for the ~60-line implementation.

Build your first plugin

Create the folder structure:

mkdir -p abilities/hello/0.0.1

Add abilities/hello/0.0.1/index.js:

export default function hello(ctx) {
  ctx.commander
    .command('hello')
    .description('Prints a greeting')
    .action(() => {
      ctx.logger.log('👋  Hello from my first KADI plugin!');
    });
}

{
  "cliPlugins": {
    "hello": "abilities/hello/0.0.1"
  }
}

Run it:

kadi hello

No additional SDKs or build steps are required; providing an ES module that matches the signature is sufficient.

Plugin Atlas

KADI's power comes from its plugin ecosystem. Each plugin extends the CLI with specific functionality, from development tools to deployment automation. Here's a comprehensive guide to all official plugins:

Core Development Plugins

kadi-install

Purpose: The foundation of KADI's dependency management system. Installs abilities and their nested dependencies, resolving version conflicts and updating agent.json automatically.

Basic Usage:

# Install a single ability
kadi install logging

# Install specific version
kadi install [email protected]

# Install multiple abilities
kadi install logging [email protected] analytics

# Install all abilities declared in agent.json
kadi install

# Install CLI dependencies (from KADI CLI's agent.json)
kadi install --cli

Repository: kadi-install

kadi-init

Purpose: Interactive project scaffolding that creates new KADI agents, CLI plugins, and abilities with proper structure and templates.

Basic Usage:

# Start interactive project creation
kadi init

# Creates a new agent with proper structure:
# - agent.json manifest
# - Language-specific dependencies
# - Main entry point with "Hello World" example
# - README with next steps

Example Output:

🚀 Welcome to KADI Init!
Let's create a new KADI project together.

? What are you building? › Agent - A standalone KADI agent
? What is the name of your project? › my-awesome-agent
? What programming language do you want to use? › JavaScript (Node.js)
? Describe your project: › A smart AI assistant for task management

📋 Project Summary:
Type: agent
Name: my-awesome-agent
Language: JavaScript
Description: A smart AI assistant for task management

? Create the project with these settings? › Yes

Creating your KADI project...
✔ Project created successfully!

🎉 Your KADI project is ready!

Repository: kadi-init

kadi-update

Purpose: Keeps your KADI projects up-to-date by checking the registry for newer versions of installed abilities and updating them automatically.

Basic Usage:

# Update all abilities in current project
kadi update

# Update the CLI itself
kadi update --cli

# Update specific abilities
kadi update logging [email protected]

# Update specific CLI abilities
kadi update --cli kadi-install [email protected]

Repository: kadi-update

Runtime & Execution Plugins

kadi-run

Purpose: The script execution engine for the KADI ecosystem. It provides a unified interface to run commands defined in agent.json files, whether they're at the project level or within specific abilities.

Basic Usage:

# Run the default 'start' script from your project
kadi run

# Run a custom script defined in your project
kadi run test

# Run a well-known script (start, init, setup)
kadi run setup

# Run a script from a specific ability
kadi run build --ability my-ui

# Run a script with explicit ability specification
kadi run -a data-processor migrate

Advanced Usage:

# Development workflow
kadi run init      # Initialize project dependencies
kadi run dev       # Start development server
kadi run test      # Run tests
kadi run build     # Build for production

# Ability management
kadi run setup --ability ui-component    # Run setup from ui-component ability
kadi run build --ability api-client      # Run build from api-client ability
kadi run test --ability data-processor   # Run tests from data-processor ability

# Custom scripts
kadi run deploy    # Run deployment script
kadi run migrate --ability data-processor  # Execute database migrations
kadi run docs      # Generate documentation

Repository: kadi-run

Build & Deployment Plugins

kadi-build

Purpose: Containerizes KADI agents into reproducible Docker images using a curated Dockerfile.KADI template.

Basic Usage:

# Build with default settings
kadi build

# Custom image tag
kadi build --tag registry.example.com/agents/my-agent:1.2.0

# Cross-compile for Linux/AMD64
kadi build --platform linux

# Preview changes without building
kadi build --dry-run

Repository: kadi-build

kadi-deploy

Purpose: Deployment engine that takes a single agent.json and deploys to various platforms, generating the necessary artifacts and executing the deployment process.

Basic Usage:

# Deploy locally with Podman Compose (auto-starts VM if needed)
kadi deploy --target local

# Deploy to Akash mainnet (handles wallet connection, bidding, manifest upload)
kadi deploy --target akash --network mainnet

# Preview deployment without making changes
kadi deploy --dry-run

# Non-interactive deployment (assumes "yes" for all prompts)
kadi deploy --target akash --network mainnet --yes

Advanced Usage:

# Deploy to specific project directory
kadi deploy --target local --project /path/to/agent

# Deploy to Akash testnet
kadi deploy --target akash --network testnet

# Local development workflow
kadi deploy --dry-run              # Preview compose without changes
kadi deploy --target local         # Build images and run stack locally
kadi deploy --target akash         # Deploy to Akash Network

Repository: kadi-deploy

Infrastructure Plugins

kadi-broker

Purpose: WebSocket & RabbitMQ message router for cross-agent communication, implementing the KADI protocol for tool discovery and invocation.

Basic Usage:

# Start the broker server
npm start

# Run example agents
npm run agent:a
npm run agent:b
npm run agent:c

# Monitor with observer
npm run observer

Repository: kadi-broker

Roadmap

TODO

Contributing

TODO

For larger ideas open an issue first so we can discuss direction.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

KADI CLI – Knowledge & Ability Deployment Interface

Table of Contents

What is KADI?

Key Concepts

Agents

Abilities

CLI Plugins

Getting Started

Prerequisites

Installation

Uninstallation

Create Your First Agent

For Contributors & Maintainers

Quick install (Linux & macOS)

Quick install (Windows)

agent.json – the manifest

Lifecycle Scripts

Script Execution Order

Required vs Optional Scripts

Best Practices

The Plugin Architecture

How command resolution works

Build your first plugin

Plugin Atlas

Core Development Plugins

kadi-install

kadi-init

kadi-update

Runtime & Execution Plugins

kadi-run

Build & Deployment Plugins

kadi-build

kadi-deploy

Infrastructure Plugins

kadi-broker

Roadmap

Contributing

`agent.json` – the manifest