@inkeep/agents-cli 0.47.5 → 0.48.1

package/README.md

@@ -1,624 +1,49 @@
-# Inkeep CLI
+# @inkeep/agents-cli
 
-A command-line interface for managing and interacting with Inkeep Agent Frameworks.
+CLI for working with the Inkeep Agent Framework.
 
-## Installation & Setup
-
-### Prerequisites
-
-- Node.js >= 20.x
-- pnpm package manager
-- Inkeep Agent Framework backend running (default: http://localhost:3002)
-- `@inkeep/agents-manage-ui` package installed (for visual agents orchestration)
-
-### Quick Start
-
-> **📖 For detailed setup instructions, see [SETUP.md](./SETUP.md)**
-
-1. **Install and build**
-
-   ```bash
-   # Navigate to the CLI directory
-   cd /path/to/agent-framework/agents-cli
-
-   # Install dependencies
-   pnpm install
-
-   # Build the CLI
-   pnpm build
-   ```
-
-2. **Install globally** (recommended)
-
-   **Option A: Using npm link (for development)**
-
-   ```bash
-   # Create global symlink from the agents-cli directory
-   npm link
-
-   # Verify installation
-   which inkeep  # Should show path to inkeep command
-   ```
-
-   **Option B: Using pnpm/npm global install (after publishing)**
-
-   ```bash
-   # Install the scoped package globally
-   pnpm add -g @inkeep/agents-cli
-   # or
-   npm install -g @inkeep/agents-cli
-
-   # Verify installation
-   inkeep --version
-   ```
-
-   **Note:**
-
-   - For local development, use `npm link` (more reliable than `pnpm link --global`)
-   - The command is still `inkeep` even though the package name is `@inkeep/agents-cli`
-   - If linking fails, try unlinking first: `npm unlink -g @inkeep/agents-cli`
-
-3. **Install the dashboard package (for visual agents orchestration)**
+## Install
 
 ```bash
-# Install the dashboard UI package for visual agents orchestration
-npm install @inkeep/agents-manage-ui
+npm install -g @inkeep/agents-cli
 # or
-pnpm add @inkeep/agents-manage-ui
-```
-
-4. **Configure your project**
-
-```bash
-# Create an inkeep.config.ts file with your tenant ID
-inkeep init
-
-# Or manually create inkeep.config.ts:
-# export default defineConfig({
-#   tenantId: "your-tenant-id",
-#   projectId: "your-project-id",
-#   agentsApiUrl: "http://localhost:3002",
-# });
-```
-
-## Configuration
-
-### Configuration Sources (priority order)
-
-1. **Command-line flags** - Highest priority (e.g., `--tenant-id`, `--agents-api-url`, `--config`)
-2. **Config file** - `inkeep.config.ts` (or file specified with `--config`)
-3. **Environment variables** - `INKEEP_AGENTS_API_URL`
-4. **Defaults** - Lowest priority (defaults to `http://localhost:3002`)
-
-### Config File Options
-
-Most commands support the `--config` option to specify a custom configuration file:
-
-```bash
-# Use custom config file
-inkeep list-graphs --project my-project --config ./staging-config.ts
-
-# Backward compatibility (deprecated)
-inkeep list-graphs --project my-project --config-file-path ./staging-config.ts
-```
-
-### Environment Variables
-
-Create a `.env` file in your project directory:
-
-```bash
-INKEEP_AGENTS_API_URL=http://localhost:3002
+pnpm add -g @inkeep/agents-cli
 ```
 
-Or export them in your shell:
+The executable command is `inkeep`.
 
-```bash
-export INKEEP_AGENTS_API_URL=http://localhost:3002
-```
-
-## Commands
+## Docs
 
-### `inkeep add [template]`
+- CLI overview: <https://docs.inkeep.com/guides/cli/overview>
+- CLI reference: <https://docs.inkeep.com/typescript-sdk/cli-reference>
+- Push guide: <https://docs.inkeep.com/guides/cli/push-to-cloud>
+- Pull guide: <https://docs.inkeep.com/guides/cli/pull-from-cloud>
+- Profile setup: <https://docs.inkeep.com/guides/cli/setup-profile>
 
-Pull a template project from the [Inkeep Agents Cookbook](https://github.com/inkeep/agents/tree/main/agents-cookbook/template-projects).
+## Quick usage
 
 ```bash
-# Add a template
-inkeep add my-template
-
-# Add template to specific path
-inkeep add my-template --target-path ./src/templates
-
-# Using config file
-inkeep add my-template --config ./my-config.ts
-```
-
-### `inkeep init [path]`
-
-Initialize a new Inkeep configuration file.
-
-```bash
-# Interactive initialization
 inkeep init
-
-# Initialize in specific directory
-inkeep init ./my-project
-
-# Skip interactive prompts
-inkeep init --no-interactive
-
-# Use existing config as template
-inkeep init --config ./template-config.ts
-```
-
-### `inkeep config`
-
-Manage Inkeep configuration values.
-
-```bash
-# Get configuration value
-inkeep config get tenantId
-
-# Set configuration value
-inkeep config set tenantId my-tenant-id
-
-# List all configuration values
-inkeep config list
-
-# Using specific config file
-inkeep config get tenantId --config ./my-config.ts
-```
-
-### `inkeep pull`
-
-Pull entire project configuration from backend and update local files.
-
-```bash
-# Pull current project
-inkeep pull
-
-# Pull specific project
-inkeep pull --project my-project-id
-
-# Generate environment file
-inkeep pull --env production
-
-# Generate JSON file instead of updating files
-inkeep pull --json
-
-# Enable debug logging
-inkeep pull --debug
-
-# Using config file
-inkeep pull --project my-project-id --config ./my-config.ts
-```
-
-### `inkeep dev`
-
-Start the Inkeep dashboard server, build for production, or export the Next.js project.
-
-```bash
-# Start development server
-inkeep dev
-
-# Start on custom port and host
-inkeep dev --port 3001 --host 0.0.0.0
-
-# Build for production (packages standalone build)
-inkeep dev --build --output-dir ./build
-
-# Export Next.js project source files
-inkeep dev --export --output-dir ./my-dashboard
-
-# Get dashboard path for deployment
-DASHBOARD_PATH=$(inkeep dev --path)
-echo "Dashboard built at: $DASHBOARD_PATH"
-
-# Use with Vercel
-vercel --cwd $(inkeep dev --path) -Q .vercel build
-
-# Use with Docker
-docker build -t inkeep-dashboard $(inkeep dev --path)
-
-# Use with other deployment tools
-rsync -av $(inkeep dev --path)/ user@server:/var/www/dashboard/
-```
-
-### `inkeep tenant [tenant-id]` ⚠️ NOT IMPLEMENTED
-
-> **⚠️ WARNING: This command is not yet implemented in the current CLI.**
-> Use `inkeep.config.ts` to set your tenant ID instead.
-
-Manage tenant configuration.
-
-```bash
-# Set tenant ID
-inkeep tenant my-tenant
-
-# View current tenant ID
-inkeep tenant
-```
-
-### `inkeep list-graphs`
-
-List all available graphs for a specific project.
-
-```bash
-# List graphs for a project (required)
-inkeep list-graphs --project my-project-id
-
-# With custom API URL
-inkeep list-graphs --project my-project-id --agent-api-url http://api.example.com:3002
-
-# With custom tenant ID
-inkeep list-graphs --project my-project-id --tenant-id my-tenant-id
-
-# Using config file
-inkeep list-agents --project my-project-id --config ./my-config.ts
-```
-
-Output:
-
-```
-┌─────────────────────────┬────────────────────┬───────────────┬───────────┐
-│ Agent ID                │ Name               │ Default Agent │ Created   │
-├─────────────────────────┼────────────────────┼───────────────┼───────────┤
-│ customer-support-graph  │ Customer Support   │ router        │ 1/15/2025 │
-│ qa-assistant           │ QA Assistant       │ qa-agent      │ 1/14/2025 │
-└─────────────────────────┴────────────────────┴───────────────┴───────────┘
-```
-
-### `inkeep push`
-
-Push your project configuration to the backend.
-
-```bash
-# Push the current project (from the directory with inkeep.config.ts)
 inkeep push
-
-# Push specific project
-inkeep push --project my-project-id
-
-# With custom configuration
-inkeep push --project my-project-id --config ./my-config.ts
-
-# With custom API URLs
-inkeep push --project my-project-id --agents-api-url http://api.example.com
-
-# With custom tenant ID
-inkeep push --project my-project-id --tenant-id my-tenant-id
-```
-
-**Features:**
-
-- Automatically injects tenant ID and API URL from `inkeep.config.ts`
-- Validates exactly one Agent is exported
-- Warns about dangling resources (unreferenced agents/tools)
-- Shows graph summary after successful push
-- Handles graph initialization automatically
-
-**Agent files:** Define your agents in your project (e.g., `agents/*.ts`). The CLI pushes the project containing those agents.
-
-**Example graph configuration:**
-
-```javascript
-// customer-support.agent.ts
-import { agent, subAgent, tool } from "@inkeep/agents-sdk";
-
-const assistantSubAgent = subAgent({
-  id: "assistant",
-  name: "Assistant",
-  prompt: "Help users with their questions",
-  canUse: () => [searchTool],
-  // No tenantId needed - injected by CLI
-});
-
-// Must export exactly one agent
-export const myAgent = agent({
-  id: "my-assistant",
-  name: "My Assistant",
-  defaultSubAgent: assistantSubAgent,
-  subAgents: () => [assistantSubAgent],
-  // No tenantId or apiUrl needed - CLI injects from config
-});
-// No agent.init() call - CLI handles initialization
-```
-
-### `inkeep mcp start <graph-file>` ⚠️ NOT IMPLEMENTED
-
-> **⚠️ WARNING: This command is not yet implemented in the current CLI.**
-> MCP functionality is planned but not available in the current version.
-
-Start MCP (Model Context Protocol) servers defined in a graph file.
-
-```bash
-# Start MCP servers from a TypeScript agent file
-inkeep mcp start examples/agent-configurations/weather-agent.ts
-
-# Start from compiled JavaScript
-inkeep mcp start dist/examples/agent-configurations/weather-agent.js
-
-# Run in detached mode
-inkeep mcp start my-agent.ts --detached
-
-# Show verbose output
-inkeep mcp start my-agent.ts --verbose
-```
-
-**Features:**
-
-- Supports both TypeScript (`.ts`) and JavaScript (`.js`) files
-- Automatically allocates ports for local servers (3100-3200)
-- Shows server names, ports, and URLs
-- Distinguishes between local (🏠) and remote (☁️) servers
-
-### `inkeep mcp stop` ⚠️ NOT IMPLEMENTED
-
-> **⚠️ WARNING: This command is not yet implemented in the current CLI.**
-
-Stop running MCP servers.
-
-```bash
-# Stop all servers
-inkeep mcp stop --all
-
-# Stop servers for a specific graph
-inkeep mcp stop --graph customer-support-graph
-```
-
-### `inkeep mcp status` ⚠️ NOT IMPLEMENTED
-
-> **⚠️ WARNING: This command is not yet implemented in the current CLI.**
-
-Show status of all MCP servers.
-
-```bash
-inkeep mcp status
-```
-
-Output shows:
-
-- Process ID
-- Graph ID
-- Tool name
-- Port/URL
-- Running status
-- Uptime
-
-### `inkeep mcp list` ⚠️ NOT IMPLEMENTED
-
-> **⚠️ WARNING: This command is not yet implemented in the current CLI.**
-
-List all MCP servers with detailed information.
-
-```bash
-# Default tree view
-inkeep mcp list
-
-# Table format
-inkeep mcp list --format table
-
-# Verbose output (includes descriptions)
-inkeep mcp list --verbose
+inkeep pull
+inkeep list-agent --project <project-id>
 ```
 
-## Complete Workflow Example
-
-### Basic Setup
+## Local development
 
 ```bash
-# Install and link CLI
-cd agents-cli
 pnpm install
 pnpm build
 npm link
-
-# Initialize configuration
-inkeep init
-# Edit inkeep.config.ts to set your tenantId and projectId
-```
-
-### Working with Graphs and MCP Servers ⚠️ NOT AVAILABLE
-
-> **⚠️ WARNING: MCP commands shown below are not yet implemented.**
-> This section shows planned functionality that is not available in the current version.
-
-1. **Create an agent with MCP tools** (`my-agent.ts`)
-
-```typescript
-import {
-  agent,
-  subAgent,
-  mcpServer,
-} from "@inkeep/agents-sdk";
-
-// Define MCP servers (tools)
-const randomNumberServer = mcpServer({
-  name: "random_number",
-  description: "Generates a random number",
-  execute: async () => Math.random(),
-});
-
-const weatherServer = mcpServer({
-  name: "weather_api",
-  description: "Get weather information",
-  serverUrl: "https://api.weather.example.com/mcp",
-});
-
-// Define sub-agents
-const assistantSubAgent = subAgent({
-  id: "assistant",
-  name: "Assistant",
-  prompt: "Help users with various tasks",
-  canUse: () => [randomNumberServer, weatherServer],
-});
-
-// Export the agent
-export const myAgent = agent({
-  id: "my-assistant",
-  name: "My Assistant",
-  defaultSubAgent: assistantSubAgent,
-  subAgents: () => [assistantSubAgent],
-});
-
-// Export servers for MCP management
-export const servers = [randomNumberServer, weatherServer];
-```
-
-2. **Monitor and manage servers**
-
-```bash
-# Check server status
-inkeep mcp status
-
-# List all servers with details
-inkeep mcp list
-
-# Stop servers when done
-inkeep mcp stop --all
+inkeep --version
 ```
 
-## Working with Different Environments
+## Contributing
 
-### Development
-
-```bash
-# Using environment variables
-INKEEP_AGENTS_MANAGE_API_URL=http://localhost:3002 inkeep list-graphs
-
-# Using .env file
-echo "INKEEP_AGENTS_API_URL=http://localhost:3002" > .env
-```
-
-### Staging
-
-```bash
-# Set in config file
-# Edit your inkeep.config.ts:
-# agentsApiUrl: 'https://staging-api.example.com'
-```
-
-### Production
-
-```bash
-# Using environment variables
-export INKEEP_AGENTS_API_URL=https://inkeep-api.example.com
-inkeep list-graphs
-```
-
-## Development
-
-### Running from Source
-
-```bash
-# Without building (using tsx)
-pnpm tsx src/index.ts <command>
-
-# After building
-node dist/index.js <command>
-
-# Watch mode (auto-rebuild on changes)
-pnpm dev
-```
-
-### Testing
-
-```bash
-# Run tests
-pnpm test
-
-# Watch mode
-pnpm test:watch
-
-# Coverage report
-pnpm test:coverage
-```
-
-### Type Checking
+Run from `agents-cli/`:
 
 ```bash
+pnpm lint
 pnpm typecheck
+pnpm test --run
 ```
-
-### Project Structure
-
-```
-agents-cli/
-├── src/
-│   ├── index.ts              # Main CLI entry point
-│   ├── config.ts             # Configuration management
-│   ├── api.ts                # API client for backend
-│   ├── commands/             # Command implementations
-│   │   ├── push.ts           # Push graph configurations
-│   │   ├── tenant.ts         # Tenant management
-│   │   └── list-graphs.ts    # List graphs
-│   ├── types/                # TypeScript declarations
-│   └── __tests__/            # Test files
-├── dist/                     # Compiled JavaScript
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-## Troubleshooting
-
-### Common Issues
-
-**"Failed to fetch graphs" or connection errors**
-
-```bash
-# Check if backend is running
-curl http://localhost:3002/health
-
-# Verify API URLs
-echo $INKEEP_AGENTS_API_URL
-
-# Try with explicit URL and project
-inkeep list-graphs --project my-project-id --agents-api-url http://localhost:3002
-```
-
-**Command not found: inkeep**
-
-```bash
-# Ensure CLI is linked globally
-cd agents-cli
-npm link
-
-# Or if published, install globally
-pnpm add -g @inkeep/agents-cli
-# or
-npm install -g @inkeep/agents-cli
-
-# Or add to PATH manually (for development)
-export PATH="$PATH:/path/to/agents-cli/dist"
-```
-
-## Dependencies
-
-### Runtime Dependencies
-
-- **commander**: Command-line framework
-- **chalk**: Terminal styling
-- **dotenv**: Environment variable loading
-- **ora**: Loading spinners
-- **cli-table3**: Table formatting
-- **inquirer**: Interactive prompts
-- **inquirer-autocomplete-prompt**: Searchable selections
-
-### Development Dependencies
-
-- **typescript**: TypeScript compiler
-- **@types/node**: Node.js types
-- **vitest**: Testing framework
-- **@vitest/coverage-v8**: Coverage reporting
-
-## Requirements
-
-- Node.js >= 20.x
-- pnpm package manager
-- TypeScript 5.x
-- Inkeep Agent Framework backend
-
-## License
-
-MIT

package/dist/api.js

@@ -141,6 +141,66 @@ var ManagementApiClient = class ManagementApiClient extends BaseApiClient {
 		}
 		return allProjects;
 	}
+	async getDataComponent(componentId) {
+		const tenantId = this.checkTenantId();
+		const projectId = this.getProjectId();
+		const response = await this.authenticatedFetch(`${this.apiUrl}/manage/tenants/${tenantId}/projects/${projectId}/data-components/${componentId}`, { method: "GET" });
+		if (response.status === 404) return null;
+		if (!response.ok) {
+			const err = await response.text().catch(() => "");
+			throw new Error(`Failed to fetch data component: ${response.statusText}${err ? `\n${err}` : ""}`);
+		}
+		return (await response.json()).data ?? null;
+	}
+	async listDataComponents() {
+		const tenantId = this.checkTenantId();
+		const projectId = this.getProjectId();
+		const all = [];
+		let page = 1;
+		const limit = 100;
+		let result;
+		do {
+			const response = await this.authenticatedFetch(`${this.apiUrl}/manage/tenants/${tenantId}/projects/${projectId}/data-components?page=${page}&limit=${limit}`, { method: "GET" });
+			if (!response.ok) {
+				const err = await response.text().catch(() => "");
+				throw new Error(`Failed to list data components: ${response.statusText}${err ? `\n${err}` : ""}`);
+			}
+			result = await response.json();
+			all.push(...result.data || []);
+			page++;
+		} while (result.data?.length === limit && all.length < (result.pagination?.total ?? 0));
+		return all;
+	}
+	async getArtifactComponent(componentId) {
+		const tenantId = this.checkTenantId();
+		const projectId = this.getProjectId();
+		const response = await this.authenticatedFetch(`${this.apiUrl}/manage/tenants/${tenantId}/projects/${projectId}/artifact-components/${componentId}`, { method: "GET" });
+		if (response.status === 404) return null;
+		if (!response.ok) {
+			const err = await response.text().catch(() => "");
+			throw new Error(`Failed to fetch artifact component: ${response.statusText}${err ? `\n${err}` : ""}`);
+		}
+		return (await response.json()).data ?? null;
+	}
+	async listArtifactComponents() {
+		const tenantId = this.checkTenantId();
+		const projectId = this.getProjectId();
+		const all = [];
+		let page = 1;
+		const limit = 100;
+		let result;
+		do {
+			const response = await this.authenticatedFetch(`${this.apiUrl}/manage/tenants/${tenantId}/projects/${projectId}/artifact-components?page=${page}&limit=${limit}`, { method: "GET" });
+			if (!response.ok) {
+				const err = await response.text().catch(() => "");
+				throw new Error(`Failed to list artifact components: ${response.statusText}${err ? `\n${err}` : ""}`);
+			}
+			result = await response.json();
+			all.push(...result.data || []);
+			page++;
+		} while (result.data?.length === limit && all.length < (result.pagination?.total ?? 0));
+		return all;
+	}
 };
 var ExecutionApiClient = class ExecutionApiClient extends BaseApiClient {
 	constructor(apiUrl, tenantId, projectId, apiKey, isCI = false) {

package/dist/commands/add-ui.js

@@ -0,0 +1,179 @@
+import { ManagementApiClient } from "../api.js";
+import { findConfigFile, findProjectConfig } from "../utils/config.js";
+import { initializeCommand } from "../utils/cli-pipeline.js";
+import path from "node:path";
+import * as p from "@clack/prompts";
+import chalk from "chalk";
+import { findUp } from "find-up";
+import fs from "fs-extra";
+import { Project } from "ts-morph";
+
+//#region src/commands/add-ui.ts
+const UI_DIR_RELATIVE = "apps/agents-ui/src/ui";
+function toPascalCase(name) {
+	if (!name?.trim()) return "Component";
+	return name.trim().replace(/[-_]+/g, " ").split(/\s+/).map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join("");
+}
+/**
+* Ensures the component declaration is exported using AST. Finds the first
+* function or const component (PascalCase name) and adds export if missing.
+*/
+function ensureExported(code) {
+	try {
+		const sourceFile = new Project({
+			useInMemoryFileSystem: true,
+			compilerOptions: { jsx: 1 }
+		}).createSourceFile("temp.tsx", code);
+		const candidates = [];
+		for (const fn of sourceFile.getFunctions()) if (fn.getName()) candidates.push({
+			start: fn.getStart(),
+			type: "function",
+			node: fn
+		});
+		for (const stmt of sourceFile.getVariableStatements()) {
+			const name = stmt.getDeclarationList().getDeclarations()[0]?.getName?.();
+			if (typeof name === "string" && name.length > 0 && name[0] === name[0].toUpperCase()) candidates.push({
+				start: stmt.getStart(),
+				type: "variable",
+				node: stmt
+			});
+		}
+		candidates.sort((a, b) => a.start - b.start);
+		const first = candidates[0];
+		if (!first) return code;
+		if (first.type === "function") {
+			if (!first.node.isExported()) first.node.setIsExported(true);
+		} else if (!first.node.hasExportKeyword()) first.node.toggleModifier("export", true);
+		return sourceFile.getFullText();
+	} catch {
+		return code;
+	}
+}
+async function findUiDirectory() {
+	const cwd = process.cwd();
+	const uiDir = path.join(cwd, UI_DIR_RELATIVE);
+	if (await fs.pathExists(uiDir)) return uiDir;
+	const found = await findUp(UI_DIR_RELATIVE, { type: "directory" });
+	if (found) return found;
+	const agentsUi = await findUp("apps/agents-ui", { type: "directory" });
+	if (agentsUi) return path.join(agentsUi, "src", "ui");
+	return path.join(cwd, UI_DIR_RELATIVE);
+}
+async function fetchAllComponentsWithRender(client) {
+	const [dataComponents, artifactComponents] = await Promise.all([client.listDataComponents(), client.listArtifactComponents()]);
+	return {
+		data: dataComponents,
+		artifact: artifactComponents
+	};
+}
+function formatComponentList(data, artifact) {
+	const withRender = (c) => c.render?.component?.trim();
+	const lines = [];
+	for (const c of data.filter(withRender)) lines.push(`  ${chalk.cyan(c.id)}  ${chalk.gray("(data)")}     ${c.name}`);
+	for (const c of artifact.filter(withRender)) lines.push(`  ${chalk.cyan(c.id)}  ${chalk.gray("(artifact)")}  ${c.name}`);
+	return lines.length ? lines.join("\n") : "  (none with render code)";
+}
+async function addUiCommand(options) {
+	const componentId = typeof options.ui === "string" ? options.ui : void 0;
+	const configPath = options.config ? path.resolve(process.cwd(), options.config) : findConfigFile(process.cwd());
+	if (!configPath) {
+		console.error(chalk.red("No Inkeep config found. Run from a project directory with inkeep.config.ts or pass --config <path>."));
+		process.exit(1);
+	}
+	const { config, isCI } = await initializeCommand({
+		configPath,
+		profileName: options.profile,
+		showSpinner: true,
+		spinnerText: "Loading configuration...",
+		logConfig: !options.quiet,
+		quiet: options.quiet
+	});
+	const projectId = (await findProjectConfig(path.dirname(configPath)))?.projectId ?? null;
+	if (!projectId) {
+		console.error(chalk.red("Project ID not found in config. Set projectId in your inkeep.config.ts."));
+		process.exit(1);
+	}
+	if (!config.agentsApiKey) {
+		console.error(chalk.red("Not authenticated. Run \"inkeep login\" or set agentsApi.apiKey in your config."));
+		process.exit(1);
+	}
+	let client;
+	try {
+		client = await ManagementApiClient.create(config.agentsApiUrl, configPath, config.tenantId, projectId, isCI ?? false, config.agentsApiKey);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		console.error(chalk.red(`Failed to create API client: ${message}`));
+		process.exit(1);
+	}
+	const toWrite = [];
+	const s = p.spinner();
+	if (options.list) {
+		s.start("Fetching components...");
+		const { data: dataComponents, artifact: artifactComponents } = await fetchAllComponentsWithRender(client);
+		s.stop();
+		console.log(chalk.cyan("\nAvailable UI components (use id with inkeep add --ui <id>):\n"));
+		console.log(formatComponentList(dataComponents, artifactComponents));
+		console.log("");
+		process.exit(0);
+	}
+	s.start("Resolving UI directory...");
+	const uiDir = await findUiDirectory();
+	await fs.ensureDir(uiDir);
+	s.stop();
+	if (componentId) {
+		let comp = await client.getDataComponent(componentId);
+		let kind = "data";
+		if (!comp) {
+			comp = await client.getArtifactComponent(componentId);
+			kind = "artifact";
+		}
+		if (!comp) {
+			s.start("Fetching available components...");
+			const { data: dataComponents, artifact: artifactComponents } = await fetchAllComponentsWithRender(client);
+			s.stop();
+			console.error(chalk.red(`Component "${componentId}" not found (tried data and artifact components).`));
+			console.log(chalk.cyan("\nAvailable UI components (use id with inkeep add --ui <id>):\n"));
+			console.log(formatComponentList(dataComponents, artifactComponents));
+			console.log("");
+			process.exit(1);
+		}
+		if (!comp.render?.component?.trim()) {
+			console.error(chalk.red(`Component "${comp.name}" (${kind}) has no render code. Generate a render in the dashboard first.`));
+			process.exit(1);
+		}
+		const pascalName = toPascalCase(comp.name);
+		toWrite.push({
+			pascalName,
+			code: ensureExported(comp.render.component)
+		});
+	} else {
+		s.start("Fetching data and artifact components...");
+		const [dataComponents, artifactComponents] = await Promise.all([client.listDataComponents(), client.listArtifactComponents()]);
+		s.stop();
+		const withRender = (c) => c.render?.component?.trim() ? {
+			pascalName: toPascalCase(c.name),
+			code: ensureExported(c.render.component)
+		} : null;
+		for (const c of dataComponents) {
+			const item = withRender(c);
+			if (item) toWrite.push(item);
+		}
+		for (const c of artifactComponents) {
+			const item = withRender(c);
+			if (item) toWrite.push(item);
+		}
+		if (toWrite.length === 0) {
+			console.log(chalk.yellow("No components with render code found. Generate renders in the dashboard first."));
+			process.exit(0);
+		}
+	}
+	s.start(`Writing ${toWrite.length} component(s) to ${uiDir}...`);
+	for (const { pascalName, code } of toWrite) {
+		const filePath = path.join(uiDir, `${pascalName}.tsx`);
+		await fs.writeFile(filePath, code, "utf-8");
+	}
+	s.stop(chalk.green(`Added ${toWrite.length} component(s) to ${path.relative(process.cwd(), uiDir)}. Import with: import { <Name> } from './ui/<Name>';`));
+}
+
+//#endregion
+export { addUiCommand, ensureExported };

package/dist/commands/add.js

@@ -1,4 +1,5 @@
 import { cloneTemplate, cloneTemplateLocal, getAvailableTemplates } from "../utils/templates.js";
+import { addUiCommand } from "./add-ui.js";
 import { ANTHROPIC_MODELS, GOOGLE_MODELS, OPENAI_MODELS } from "@inkeep/agents-core";
 import path from "node:path";
 import * as p from "@clack/prompts";
@@ -23,6 +24,16 @@ const defaultAnthropicModelConfigurations = {
 	summarizer: { model: ANTHROPIC_MODELS.CLAUDE_SONNET_4_5 }
 };
 async function addCommand(options) {
+	if (options.ui !== void 0) {
+		await addUiCommand({
+			ui: options.ui,
+			list: options.list,
+			config: options.config,
+			profile: options.profile,
+			quiet: options.quiet
+		});
+		return;
+	}
 	const projectTemplates = await getAvailableTemplates("template-projects", options.localPrefix);
 	const mcpTemplates = await getAvailableTemplates("template-mcps", options.localPrefix);
 	if (!options.project && !options.mcp) {

package/dist/commands/pull-v3/components/project-generator.js

@@ -20,6 +20,7 @@ function generateProjectDefinition(projectId, projectData, style = DEFAULT_STYLE
 	lines.push(`${indentation}name: ${formatString(projectData.name, q)},`);
 	if (shouldInclude(projectData.description)) lines.push(`${indentation}description: ${formatString(projectData.description, q, true)},`);
 	if (shouldInclude(projectData.models)) lines.push(`${indentation}models: ${formatObject(projectData.models, style, 2)},`);
+	if (shouldInclude(projectData.skills)) lines.push(`${indentation}skills: () => loadSkills(path.join(${formatString(projectId, q)}, 'skills')),`);
 	if (shouldInclude(projectData.stopWhen)) {
 		lines.push(`${indentation}stopWhen: {`);
 		if (projectData.stopWhen.transferCountIs !== void 0) lines.push(`${indentation}${indentation}transferCountIs: ${projectData.stopWhen.transferCountIs}, // Max transfers for agents`);
@@ -64,7 +65,14 @@ function generateProjectDefinition(projectId, projectData, style = DEFAULT_STYLE
 */
 function generateProjectImports(projectData, style = DEFAULT_STYLE, registry) {
 	const imports = [];
-	imports.push(generateImport(["project"], "@inkeep/agents-sdk", style));
+	const sdkImports = ["project"];
+	if (shouldInclude(projectData.skills)) sdkImports.push("loadSkills");
+	imports.push(generateImport(sdkImports, "@inkeep/agents-sdk", style));
+	if (shouldInclude(projectData.skills)) {
+		const q = style.quotes === "single" ? "'" : "\"";
+		const semi = style.semicolons ? ";" : "";
+		imports.push(`import path from ${q}node:path${q}${semi}`);
+	}
 	if (registry) {
 		const currentFilePath = "index.ts";
 		const referencedComponents = [];
@@ -83,8 +91,8 @@ function generateProjectImports(projectData, style = DEFAULT_STYLE, registry) {
 			else if (typeof projectData.tools === "object") toolIds = Object.keys(projectData.tools);
 			for (const toolId of toolIds) {
 				let componentType = "tools";
-				if (registry?.get(toolId, "functionTools")) componentType = "functionTools";
-				else if (registry?.get(toolId, "tools")) componentType = "tools";
+				if (registry.get(toolId, "functionTools")) componentType = "functionTools";
+				else if (registry.get(toolId, "tools")) componentType = "tools";
 				referencedComponents.push({
 					id: toolId,
 					type: componentType
@@ -138,7 +146,11 @@ function generateProjectImports(projectData, style = DEFAULT_STYLE, registry) {
 * Generate complete project file (imports + definition)
 */
 function generateProjectFile(projectId, projectData, style = DEFAULT_STYLE, registry) {
-	return generateFileContent(generateProjectImports(projectData, style, registry), [generateProjectDefinition(projectId, projectData, style, registry)]);
+	const imports = generateProjectImports(projectData, style, registry);
+	const definition = generateProjectDefinition(projectId, projectData, style, registry);
+	const definitions = [];
+	definitions.push(definition);
+	return generateFileContent(imports, definitions);
 }
 
 //#endregion

package/dist/commands/pull-v3/components/skill-generator.js

@@ -0,0 +1,23 @@
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { mkdir, writeFile } from "node:fs/promises";
+
+//#region src/commands/pull-v3/components/skill-generator.ts
+function formatMetadata(metadata) {
+	return `metadata:\n${stringify(metadata).split("\n").filter((line) => line.trim() !== "").map((line) => `  ${line}`).join("\n")}`;
+}
+async function generateSkills(skills, skillsDir) {
+	await mkdir(skillsDir, { recursive: true });
+	for (const [skillId, skill] of Object.entries(skills)) {
+		const parts = ["---", `name: ${JSON.stringify(skill.name)}`];
+		parts.push(`description: ${JSON.stringify(skill.description ?? "")}`);
+		if (skill.metadata && Object.keys(skill.metadata).length > 0) parts.push(formatMetadata(skill.metadata));
+		parts.push("---", "", skill.content || "");
+		const skillDir = join(skillsDir, skillId);
+		await mkdir(skillDir, { recursive: true });
+		await writeFile(join(skillDir, "SKILL.md"), parts.join("\n"), "utf8");
+	}
+}
+
+//#endregion
+export { generateSkills };

package/dist/commands/pull-v3/components/sub-agent-generator.js

@@ -94,6 +94,16 @@ function generateSubAgentDefinition(agentId, agentData, style = DEFAULT_STYLE, r
 		removeTrailingComma(lines);
 		lines.push(`${indentation}},`);
 	}
+	if (Array.isArray(agentData.skills) && agentData.skills.length) {
+		lines.push(`${indentation}skills: () => [`);
+		for (const skill of agentData.skills) {
+			const parts = [`id: ${formatString(skill.id, q)}`];
+			parts.push(`index: ${skill.index}`);
+			if (skill.alwaysLoaded) parts.push(`alwaysLoaded: ${skill.alwaysLoaded}`);
+			lines.push(`${indentation}${indentation}{ ${parts.join(", ")} },`);
+		}
+		lines.push(`${indentation}],`);
+	}
 	if (agentData.canUse && Array.isArray(agentData.canUse) && agentData.canUse.length > 0) {
 		const toolReferences = [];
 		if (!registry) throw new Error("Registry is required for canUse generation");

package/dist/commands/pull-v3/index.js

@@ -48,7 +48,8 @@ function createProjectStructure(projectDir) {
 		environmentsDir: join(projectRoot, "environments"),
 		credentialsDir: join(projectRoot, "credentials"),
 		contextConfigsDir: join(projectRoot, "context-configs"),
-		externalAgentsDir: join(projectRoot, "external-agents")
+		externalAgentsDir: join(projectRoot, "external-agents"),
+		skillsDir: join(projectRoot, "skills")
 	};
 	Object.values(paths).forEach((dir) => {
 		if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
@@ -229,6 +230,10 @@ async function pullV3Command(options) {
 			return;
 		}
 		const paths = createProjectStructure(projectDir);
+		if (remoteProject.skills && Object.keys(remoteProject.skills).length) {
+			const { generateSkills } = await import("./components/skill-generator.js");
+			await generateSkills(remoteProject.skills, paths.skillsDir);
+		}
 		if (options.introspect) {
 			console.log(chalk.yellow("\n🔍 Introspect mode: Regenerating all files from scratch"));
 			s.start("Generating all files deterministically...");

package/dist/commands/pull-v3/new-component-generator.js

@@ -98,7 +98,8 @@ async function createNewComponents(comparison, remoteProject, localRegistry, pat
 		environmentsDir: join(paths.projectRoot, tempDirName, "environments"),
 		credentialsDir: join(paths.projectRoot, tempDirName, "credentials"),
 		contextConfigsDir: join(paths.projectRoot, tempDirName, "context-configs"),
-		externalAgentsDir: join(paths.projectRoot, tempDirName, "external-agents")
+		externalAgentsDir: join(paths.projectRoot, tempDirName, "external-agents"),
+		skillsDir: join(paths.projectRoot, tempDirName, "skills")
 	} : paths;
 	const actionText = tempDirName ? "Creating component files in temp directory..." : "Creating new component files...";
 	console.log(chalk.cyan(`\n🆕 ${actionText}`));

package/dist/commands/pull-v3/targeted-typescript-placeholders.js

@@ -1,5 +1,5 @@
-import { randomBytes } from "node:crypto";
 import { Node, Project } from "ts-morph";
+import { randomBytes } from "node:crypto";
 
 //#region src/commands/pull-v3/targeted-typescript-placeholders.ts
 /**

package/dist/commands/pull-v3/utils/component-registry.js

@@ -293,6 +293,7 @@ function registerAllComponents(project, registry) {
 	if (project.dataComponents) for (const componentId of Object.keys(project.dataComponents)) registry.register(componentId, "dataComponents", `data-components/${componentId}.ts`);
 	if (project.artifactComponents) for (const componentId of Object.keys(project.artifactComponents)) registry.register(componentId, "artifactComponents", `artifact-components/${componentId}.ts`);
 	if (project.externalAgents) for (const extAgentId of Object.keys(project.externalAgents)) registry.register(extAgentId, "externalAgents", `external-agents/${extAgentId}.ts`);
+	if (project.skills) for (const skillId of Object.keys(project.skills)) registry.register(skillId, "skills", `skills/${skillId}.md`);
 	const statusComponents = extractStatusComponents(project);
 	for (const statusId of Object.keys(statusComponents)) registry.register(statusId, "statusComponents", `status-components/${statusId}.ts`);
 	if (project.agents) for (const agentId of Object.keys(project.agents)) registry.register(agentId, "agents", `agents/${agentId}.ts`);

package/dist/index.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import "./env.js";
 import "./instrumentation.js";
 import { addCommand } from "./commands/add.js";
@@ -25,7 +26,7 @@ const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), "..", "pac
 const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
 const program = new Command();
 program.name("inkeep").description("CLI tool for Inkeep Agent Framework").version(packageJson.version);
-program.command("add [template]").description("Add a new template to the project").option("--project <template>", "Project template to add").option("--mcp <template>", "MCP template to add").option("--target-path <path>", "Target path to add the template to").option("--local-prefix <path_prefix>", "Use local templates from the given path prefix").option("--config <path>", "Path to configuration file").action(async (template, options) => {
+program.command("add [template]").description("Add a new template to the project").option("--project <template>", "Project template to add").option("--mcp <template>", "MCP template to add").option("--ui [component-id]", "Add UI component(s) to apps/agents-ui/src/ui (omit id to add all)").option("--list", "List available UI components (use with --ui)").option("--target-path <path>", "Target path to add the template to").option("--local-prefix <path_prefix>", "Use local templates from the given path prefix").option("--config <path>", "Path to configuration file").option("--profile <name>", "Profile to use for authentication").option("--quiet", "Suppress profile/config logging").action(async (template, options) => {
 	await addCommand({
 		template,
 		...options

package/dist/utils/cli-pipeline.js

@@ -1,8 +1,8 @@
 import { getCredentialExpiryInfo, loadCredentials } from "./credentials.js";
-import { ProfileManager } from "./profiles/profile-manager.js";
-import "./profiles/index.js";
 import { detectCIEnvironment, loadCIEnvironmentConfig, logCIConfig } from "./ci-environment.js";
 import { validateConfiguration } from "./config.js";
+import { ProfileManager } from "./profiles/profile-manager.js";
+import "./profiles/index.js";
 import * as p from "@clack/prompts";
 import chalk from "chalk";
 

package/dist/utils/config.js

@@ -23,19 +23,28 @@ function isNestedConfig(config) {
 	return config && config.agentsApi !== void 0;
 }
 /**
+* Ensure URL has a scheme so fetch() works. Bare host:port gets http://.
+*/
+function ensureUrlScheme(url) {
+	if (!url?.trim()) return url;
+	const u = url.trim();
+	if (/^https?:\/\//i.test(u)) return u;
+	return `http://${u}`;
+}
+/**
 * Normalize config from either flat or nested format to internal format
 */
 function normalizeConfig(config) {
 	if (isNestedConfig(config)) return {
 		tenantId: config.tenantId,
-		agentsApiUrl: config.agentsApi?.url,
+		agentsApiUrl: ensureUrlScheme(config.agentsApi?.url),
 		agentsApiKey: config.agentsApi?.apiKey,
 		manageUiUrl: config.manageUiUrl,
 		outputDirectory: config.outputDirectory
 	};
 	return {
 		tenantId: config.tenantId,
-		agentsApiUrl: config.agentsApiUrl,
+		agentsApiUrl: ensureUrlScheme(config.agentsApiUrl),
 		manageUiUrl: config.manageUiUrl,
 		outputDirectory: config.outputDirectory
 	};
@@ -254,6 +263,14 @@ async function validateConfiguration(configPath, tag) {
 		config.agentsApiKey = cliCredentials.accessToken;
 		logger.info({}, "Using CLI session token as API key");
 	}
+	if (!config.agentsApiKey && !cliCredentials) {
+		const cloudCreds = await loadCredentials("inkeep-cloud");
+		if (cloudCreds?.accessToken) {
+			config.agentsApiKey = cloudCreds.accessToken;
+			if (!config.tenantId) config.tenantId = cloudCreds.organizationId;
+			logger.info({}, "Using CLI login credentials (inkeep-cloud)");
+		}
+	}
 	if (!config.tenantId && cliCredentials) {
 		config.tenantId = cliCredentials.organizationId;
 		logger.info({}, "Using CLI organization ID as tenant ID");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkeep/agents-cli",
-  "version": "0.47.5",
+  "version": "0.48.1",
   "description": "Inkeep CLI tool",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,8 +40,8 @@
     "tsx": "^4.20.5",
     "yaml": "^2.7.0",
     "zod": "^4.3.6",
-    "@inkeep/agents-core": "^0.47.5",
-    "@inkeep/agents-sdk": "^0.47.5"
+    "@inkeep/agents-core": "^0.48.1",
+    "@inkeep/agents-sdk": "^0.48.1"
   },
   "devDependencies": {
     "@types/degit": "^2.8.6",