@kognitivedev/cli

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

Installation

bun add @kognitivedev/cli

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

bunx kognitive --help

Commands

• kognitive dev — Start backend + dashboard for local development
• kognitive build — Build all packages for production
• kognitive studio — Start only the studio dashboard
• kognitive serve — Start a standalone runtime server
• 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:

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

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:

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

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

// 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:

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 |

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

{
    "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) |

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

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

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

{
    "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:

# 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):

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):

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):

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