npm package: @kognitivedev/cli
Description: Developer CLI for Kognitive — dev, build, studio, generate
Latest version: 0.2.22

# @kognitivedev/cli

> Developer CLI for Kognitive — dev server, build, studio, and code generation.

## Installation

```bash
bun add @kognitivedev/cli
```

Once installed, the `kognitive` binary is available in your project:

```bash
bunx kognitive --help
```

## Commands

- [`kognitive dev`](#kognitive-dev) — Start backend + dashboard for local development
- [`kognitive build`](#kognitive-build) — Build all packages for production
- [`kognitive studio`](#kognitive-studio) — Start only the studio dashboard
- [`kognitive serve`](#kognitive-serve) — Start a standalone runtime server
- [`kognitive generate`](#kognitive-generate) — Scaffold agents, workflows, or tools

---

### `kognitive dev`

Start the backend API server and studio dashboard together for local development.

```
kognitive dev [options]
```

| Option | Description | Default |
| --- | --- | --- |
| `-p, --port <port>` | Backend port | `3001` |
| `--studio-port <port>` | Studio/dashboard port | `3002` |
| `--remote <url>` | Connect to a remote Kognitive instance (skips local backend) | — |

**Examples:**

```bash
# Start both backend (3001) and studio (3002)
kognitive dev

# Use custom ports
kognitive dev --port 4001 --studio-port 4002

# Connect studio to a remote backend (only starts the dashboard)
kognitive dev --remote https://api.myapp.com
```

When `--remote` is provided, the local backend is not started. Only the studio dashboard launches, with `NEXT_PUBLIC_BACKEND_URL` pointed at the remote URL.

---

### `kognitive build`

Run a production build of all packages using Turbo.

```
kognitive build
```

This executes `turbo run build` in the current working directory. All build output is streamed to stdout. Exits with code `1` on failure.

**Example:**

```bash
kognitive build
```

---

### `kognitive studio`

Start only the studio dashboard without the backend. Useful when connecting to a remote or already-running backend.

```
kognitive studio [options]
```

| Option | Description | Default |
| --- | --- | --- |
| `-p, --port <port>` | Dashboard port | `3002` |
| `--remote <url>` | Connect to a remote Kognitive instance | — |
| `--api-key <key>` | API key for remote instance | — |

**Examples:**

```bash
# Start studio on default port
kognitive studio

# Start on a custom port
kognitive studio --port 8080

# Connect to a remote backend
kognitive studio --remote https://api.myapp.com
```

---

### `kognitive serve`

Start a standalone Bun HTTP server that exposes your agents, workflows, and tools as a REST API. No Next.js, no dashboard — just a lightweight runtime server.

```
kognitive serve [options]
```

| Option | Description | Default |
| --- | --- | --- |
| `-p, --port <port>` | Server port | `2024` |
| `--config <path>` | Path to Kognitive config file | `kognitive.config.ts` |
| `--api-key <key>` | API key for authentication (also reads `RUNTIME_API_KEY` env var) | — |

**Examples:**

```bash
# Start with defaults (port 2024, config from kognitive.config.ts)
kognitive serve

# Custom port and config
kognitive serve --port 4000 --config ./my-config.ts

# Enable authentication
kognitive serve --api-key sk-my-secret-key

# Or via environment variable
RUNTIME_API_KEY=sk-my-secret-key kognitive serve
```

#### Config File

The serve command loads a Kognitive instance from a config file. The file must export a `Kognitive` instance:

```typescript
// kognitive.config.ts
import { Kognitive } from "@kognitivedev/core";
import { supportAgent } from "./src/kognitive/agents/support";
import { searchTool } from "./src/kognitive/tools/search";

export default new Kognitive({
    agents: { supportAgent },
    tools: [searchTool],
});
```

The config loader resolves exports in this order: `default` → `kognitive` → module root.

#### Authentication

When an API key is configured (via `--api-key` or `RUNTIME_API_KEY`), all requests must include a Bearer token:

```bash
curl -H "Authorization: Bearer sk-my-secret-key" http://localhost:2024/api/runtime/info
```

Unauthenticated requests receive a `401 Unauthorized` response. CORS is enabled for all origins.

#### API Endpoints

##### Runtime Info

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/api/runtime/info` | Server info: protocol version, capabilities, agent/workflow/tool counts |

```bash
curl http://localhost:2024/api/runtime/info
```

```json
{
    "protocol": "kognitive-runtime",
    "version": "1.0.0",
    "capabilities": ["agents", "workflows", "tools"],
    "agents": { "count": 2 },
    "workflows": { "count": 1 },
    "tools": { "count": 3 }
}
```

##### Agents

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/api/runtime/agents` | List all registered agents |
| `GET` | `/api/runtime/agents/:name` | Get metadata for a specific agent |
| `POST` | `/api/runtime/agents/:name/generate` | Execute an agent (non-streaming) |
| `POST` | `/api/runtime/agents/:name/stream` | Execute an agent (streaming) |

```bash
# List agents
curl http://localhost:2024/api/runtime/agents

# Get agent metadata
curl http://localhost:2024/api/runtime/agents/support

# Generate a response
curl -X POST http://localhost:2024/api/runtime/agents/support/generate \
    -H "Content-Type: application/json" \
    -d '{"messages": [{"role": "user", "content": "Hello"}]}'

# Stream a response
curl -X POST http://localhost:2024/api/runtime/agents/support/stream \
    -H "Content-Type: application/json" \
    -d '{"messages": [{"role": "user", "content": "Hello"}], "resourceId": "user-123"}'
```

The `resourceId` field is optional. When omitted, the server uses the Kognitive instance's default resource ID.

##### Workflows

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/api/runtime/workflows` | List all registered workflows |
| `GET` | `/api/runtime/workflows/:name` | Get metadata for a specific workflow |
| `POST` | `/api/runtime/workflows/:name/execute` | Execute a workflow |
| `POST` | `/api/runtime/workflows/:name/resume` | Resume a suspended workflow from a checkpoint |

```bash
# List workflows
curl http://localhost:2024/api/runtime/workflows

# Execute a workflow
curl -X POST http://localhost:2024/api/runtime/workflows/refund/execute \
    -H "Content-Type: application/json" \
    -d '{"input": {"orderId": "ORD-123"}, "resourceId": "user-456"}'

# Resume a suspended workflow
curl -X POST http://localhost:2024/api/runtime/workflows/refund/resume \
    -H "Content-Type: application/json" \
    -d '{"snapshot": {...}, "resumeData": {"approved": true}}'
```

##### Tools

| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/api/runtime/tools` | List all registered tools |
| `POST` | `/api/runtime/tools/:id/execute` | Execute a tool directly |

```bash
# List tools
curl http://localhost:2024/api/runtime/tools

# Execute a tool
curl -X POST http://localhost:2024/api/runtime/tools/search/execute \
    -H "Content-Type: application/json" \
    -d '{"input": {"query": "refund policy"}}'
```

Tool execution returns the result along with timing:

```json
{
    "result": { "query": "refund policy" },
    "durationMs": 42,
    "toolId": "search"
}
```

#### Cloud Sync

If the Kognitive instance has both `getApiKey()` and `getBaseUrl()` configured, the server automatically syncs with the Kognitive cloud on startup.

---

### `kognitive generate`

Scaffold a new agent, workflow, or tool with a starter template.

```
kognitive generate <type> <name>
```

| Argument | Description |
| --- | --- |
| `type` | One of: `agent`, `workflow`, `tool` |
| `name` | Name for the generated item (used in file name and code) |

Generated files are placed in:

| Type | Output Path |
| --- | --- |
| `agent` | `src/kognitive/agents/<name>.ts` |
| `workflow` | `src/kognitive/workflows/<name>.ts` |
| `tool` | `src/kognitive/tools/<name>.ts` |

Directories are created automatically if they don't exist. The command exits with an error if the file already exists.

**Examples:**

```bash
# Generate an agent
kognitive generate agent support
# → src/kognitive/agents/support.ts

# Generate a workflow
kognitive generate workflow refund
# → src/kognitive/workflows/refund.ts

# Generate a tool
kognitive generate tool search
# → src/kognitive/tools/search.ts
```

#### Generated Templates

**Agent** (`kognitive generate agent support`):

```typescript
import { createAgent } from "@kognitivedev/agents";
import { openai } from "@ai-sdk/openai";

export const supportAgent = createAgent({
    name: "support",
    instructions: "You are a support agent. Describe your purpose here.",
    model: openai("gpt-4o-mini"),
    maxSteps: 5,
});
```

**Workflow** (`kognitive generate workflow refund`):

```typescript
import { createWorkflow, createStep } from "@kognitivedev/workflows";
import { z } from "zod";

const processStep = createStep({
    id: "process",
    execute: async (input: any) => {
        // Your workflow logic here
        return { result: `Processed: ${JSON.stringify(input)}` };
    },
});

export const refundWorkflow = createWorkflow({ name: "refund" })
    .then(processStep)
    .build();
```

**Tool** (`kognitive generate tool search`):

```typescript
import { createTool } from "@kognitivedev/tools";
import { z } from "zod";

export const searchTool = createTool({
    id: "search",
    description: "Describe what this tool does",
    inputSchema: z.object({
        query: z.string().describe("The input query"),
    }),
    execute: async (input) => {
        // Your tool logic here
        return { result: input.query };
    },
});
```

## License

MIT