SlackStarJoin Cloud Waitlist
Typescript sdk

CLI Reference

Copy page

Complete reference for the Inkeep CLI commands

Overview

The Inkeep CLI is the primary tool for interacting with the Inkeep Agent Framework. It allows you to push Agent configurations and interact with your multi-agent system.

Installation

# Install the CLI globally
npm install -g @inkeep/agents-cli

# Install the dashboard package (for visual agents orchestration)
npm install @inkeep/agents-manage-ui

Global Options

All commands support the following global options:

  • --version - Display CLI version
  • --help - Display help for a command

Commands

inkeep init

Initialize a new Inkeep configuration file in your project.

inkeep init [path]

Options:

  • --no-interactive - Skip interactive path selection
  • --config <path> - Path to use as template for new configuration

Examples:

# Interactive initialization
inkeep init

# Initialize in specific directory
inkeep init ./my-project

# Non-interactive mode
inkeep init --no-interactive

# Use specific config as template
inkeep init --config ./template-config.ts

inkeep push

Primary use case: Push a project containing Agent configurations to your server. This command deploys your entire multi-agent project, including all Agents, Sub Agents, and tools.

inkeep push

Options:

  • --project <project-id> - Project ID or path to project directory
  • --env <environment> - Load environment-specific credentials from environments/<environment>.env.ts
  • --config <path> - Override config file path (bypasses automatic config discovery)
  • --tenant-id <id> - Override tenant ID
  • --agents-manage-api-url <url> - Override the management API URL from config
  • --agents-run-api-url <url> - Override agents run API URL
  • --json - Generate project data as JSON file instead of pushing to server

Examples:

# Push project from current directory
inkeep push

# Push specific project directory
inkeep push --project ./my-project

# Push with development environment credentials
inkeep push --env development

# Generate project JSON without pushing
inkeep push --json

# Override tenant ID
inkeep push --tenant-id my-tenant

# Override API URLs
inkeep push --agents-manage-api-url https://api.example.com
inkeep push --agents-run-api-url https://run.example.com

# Use specific config file
inkeep push --config ./custom-config/inkeep.config.ts

Environment Credentials:

The --env flag loads environment-specific credentials when pushing your project. This will look for files like environments/development.env.ts or environments/production.env.ts in your project directory and load the credential configurations defined there.

Example environment file:

// environments/development.env.ts
import { CredentialStoreType } from "@inkeep/agents-core";
import { registerEnvironmentSettings } from "@inkeep/agents-sdk";

export const development = registerEnvironmentSettings({
  credentials: {
    "api-key-dev": {
      id: "api-key-dev",
      type: CredentialStoreType.memory,
      credentialStoreId: "memory-default",
      retrievalParams: {
        key: "API_KEY_DEV",
      },
    },
  },
});

Project Discovery and Structure

The inkeep push command follows this discovery process:

  1. Config File Discovery: Searches for inkeep.config.ts using this pattern:

    • Starts from current working directory
    • Traverses upward through parent directories until found
    • Can be overridden by providing a path to the config file with the --config flag

  2. Workspace Structure: Expects this directory layout:

    workspace-root/
├── package.json              # Workspace package.json
├── tsconfig.json             # Workspace TypeScript config
├── inkeep.config.ts          # Inkeep configuration file
├── my-project/               # Individual project directory
│   ├── index.ts              # Project entry point
│   ├── agents/               # Agent definitions
│   │   └── *.ts
│   ├── tools/                # Tool definitions
│   │   └── *.ts
│   ├── data-components/      # Data component definitions
│   │   └── *.ts
│   └── environments/         # Environment-specific configs
│       ├── development.env.ts
│       └── production.env.ts
└── another-project/          # Additional projects
    └── index.ts

  3. Resource Compilation: Automatically discovers and compiles:

    • All project directories containing index.ts
    • All TypeScript files within each project directory
    • Categorizes files by type (agents, Sub Agents, tools, data components)
    • Resolves dependencies and relationships within each project

Push Behavior

When pushing, the CLI:

  • Finds and loads configuration from inkeep.config.ts at workspace root
  • Discovers all project directories containing index.ts
  • Applies environment-specific settings if --env is specified
  • Compiles all project resources defined in each project's index.ts
  • Validates Sub Agent relationships and tool configurations across all projects
  • Deploys all projects to the management API
  • Prints deployment summary with resource counts per project

inkeep pull

Pull project configuration from the server and update all TypeScript files in your local project using LLM generation.

inkeep pull

Options:

  • --project <project-id> - Project ID or path to project directory
  • --config <path> - Override config file path (bypasses automatic config discovery)
  • --agents-manage-api-url <url> - Override the management API URL from config
  • --env <environment> - Environment file to generate (development, staging, production). Defaults to development
  • --json - Save project data as JSON file instead of updating TypeScript files
  • --debug - Enable debug logging for LLM generation

Directory-Aware Pull (Mirrors inkeep push behavior):

The pull command automatically detects if you're in a project directory and pulls to that location:

  1. Automatic Detection: If your current directory contains an index.ts file that exports a project, the command automatically uses that project's ID
  2. Current Directory Pull: Files are pulled directly to your current directory (no subdirectory is created)
  3. Conflict Prevention: If you specify --project while in a project directory, an error is shown to prevent confusion

Pull Modes:

ScenarioCommandBehavior
In project directoryinkeep pull✅ Automatically detects project, pulls to current directory
In project directoryinkeep pull --project <id>❌ Error: Cannot specify --project when in project directory
Not in project directoryinkeep pullPrompts for project ID, creates subdirectory
Not in project directoryinkeep pull --project <id>Pulls specified project to subdirectory

How it Works:

The pull command discovers and updates all TypeScript files in your project based on the latest configuration from the server:

  1. File Discovery: Recursively finds all .ts files in your project (excluding environments/ and node_modules/)
  2. Smart Categorization: Categorizes files as index, agents, Sub Agents, tools, or other files
  3. Context-Aware Updates: Updates each file with relevant context from the server:
    • Agent files: Updated with specific agent data
    • Sub Agent files: Updated with specific Sub Agent configurations
    • Tool files: Updated with specific tool definitions
    • Other files: Updated with full project context
  4. LLM Generation: Uses AI to maintain code structure while updating with latest data

TypeScript Updates (Default)

By default, the pull command updates your existing TypeScript files using LLM generation:

  1. Context Preservation: Maintains your existing code structure and patterns
  2. Selective Updates: Only updates relevant parts based on server configuration changes
  3. File-Specific Context: Each file type receives appropriate context (Agents get Agent data, Sub Agents get Sub Agent data, etc.)

Examples:

# Directory-aware pull: Automatically detects project from current directory
cd my-project  # Directory contains index.ts with project export
inkeep pull    # Pulls to current directory, no subdirectory created

# Pull when NOT in a project directory (prompts for project ID)
cd ~/projects
inkeep pull    # Prompts for project ID, creates subdirectory

# Pull specific project (only works when NOT in a project directory)
cd ~/projects
inkeep pull --project my-project  # Creates my-project/ subdirectory

# Error case: --project flag in project directory
cd my-project  # Directory contains index.ts
inkeep pull --project my-project  # ERROR: Cannot specify --project in project directory

# Save project data as JSON file instead of updating files
inkeep pull --json

# Pull with custom API endpoint
inkeep pull --agents-manage-api-url https://api.example.com

# Enable debug logging
inkeep pull --debug

# Generate environment-specific credentials
inkeep pull --env production

# Use specific config file
inkeep pull --config ./custom-config/inkeep.config.ts

Model Configuration

The inkeep pull command currently uses a fixed model for LLM generation: anthropic/claude-sonnet-4-20250514.

Validation Process

The inkeep pull command includes a two-stage validation process to ensure generated TypeScript files accurately represent your backend configuration:

1. Basic File Verification

  • Checks that all expected files exist (index.ts, agent files, tool files, component files)
  • Verifies file naming conventions match (kebab-case)
  • Ensures project export is present in index.ts

2. Round-Trip Validation (New in v0.24.0)

  • Loads the generated TypeScript using the same logic as inkeep push
  • Serializes it back to JSON format
  • Compares the serialized JSON with the original backend data
  • Reports any differences found

This round-trip validation ensures:

  • ✅ Generated TypeScript can be successfully loaded and imported
  • ✅ The serialization logic (TS → JSON) works correctly
  • ✅ Generated files will work with inkeep push without errors
  • ✅ No data loss or corruption during the pull process

Validation Output:

✓ Basic file verification passed
✓ Round-trip validation passed - generated TS matches backend data

If validation fails:

The CLI will display specific differences between the generated and expected data:

✗ Round-trip validation failed

❌ Round-trip validation errors:
   The generated TypeScript does not serialize back to match the original backend data.
  • Value mismatch at agents.my-agent.name: "Original Name" vs "Generated Name"
  • Missing tool in generated: tool-id

⚠️  This indicates an issue with LLM generation or schema mappings.
The generated files may not work correctly with `inkeep push`.

TypeScript generation fails:

  • Ensure your network connectivity and API endpoints are correct
  • Check that your model provider credentials (if required by backend) are set up
  • Try using --json flag as a fallback to get the raw project data

Validation errors during pull:

  • The generated TypeScript may have syntax errors or missing dependencies
  • Check the generated file manually for obvious issues
  • Try pulling as JSON first to verify the source data: inkeep pull --json
  • If round-trip validation fails, report the issue with the error details

inkeep list-agents

List all available agents for a specific project.

inkeep list-agents --project <project-id>

Options:

  • --project <project-id> - Required. Project ID to list agents for
  • --tenant-id <tenant-id> - Tenant ID
  • --agents-manage-api-url <url> - Agents manage API URL
  • --config <path> - Path to configuration file
  • --config-file-path <path> - Path to configuration file (deprecated, use --config)

Examples:

# List agents for a specific project
inkeep list-agents --project my-project

# List agents using a specific config file
inkeep list-agents --project my-project --config ./inkeep.config.ts

# Override tenant and API URL
inkeep list-agents --project my-project --tenant-id my-tenant --agents-manage-api-url https://api.example.com

inkeep dev

Start the Inkeep dashboard server, build for production, or export the Next.js project.

Note: This command requires @inkeep/agents-manage-ui to be installed for visual agents orchestration.

inkeep dev

Options:

  • --port <port> - Port to run the server on (default: 3000)
  • --host <host> - Host to bind the server to (default: localhost)
  • --build - Build the Dashboard UI for production (packages standalone build)
  • --export - Export the Next.js project source files
  • --output-dir <dir> - Output directory for build files (default: ./inkeep-dev)
  • --path - Output the path to the Dashboard UI

Examples:

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

Manage Inkeep configuration values.

Subcommands:

inkeep config get [key]

Get configuration value(s).

inkeep config get [key]

Options:

  • --config <path> - Path to configuration file
  • --config-file-path <path> - Path to configuration file (deprecated, use --config)

Examples:

# Get all config values
inkeep config get

# Get specific value
inkeep config get tenantId

inkeep config set <key> <value>

Set a configuration value.

inkeep config set <key> <value>

Options:

  • --config <path> - Path to configuration file
  • --config-file-path <path> - Path to configuration file (deprecated, use --config)

Examples:

inkeep config set tenantId my-tenant-id
inkeep config set apiUrl http://localhost:3002

inkeep config list

List all configuration values.

inkeep config list

Options:

  • --config <path> - Path to configuration file
  • --config-file-path <path> - Path to configuration file (deprecated, use --config)

inkeep add

Pull a template project or MCP from the Inkeep Agents Cookbook.

inkeep add [options]

Options:

  • --project <name> - Add a project template
  • --mcp <name> - Add an MCP template
  • --target-path <path> - Target path to add the template to
  • --config <path> - Path to configuration file

Examples:

# List available templates (both project and MCP)
inkeep add

# Add a project template
inkeep add --project activities-planner

# Add project template to specific path
inkeep add --project activities-planner --target-path ./examples

# Add an MCP template (auto-detects apps/mcp/app directory)
inkeep add --mcp zendesk

# Add MCP template to specific path
inkeep add --mcp zendesk --target-path ./apps/mcp/app

# Using specific config file
inkeep add --project activities-planner --config ./my-config.ts

Behavior:

  • When adding an MCP template without --target-path, the CLI automatically searches for an apps/mcp/app directory in your project
  • If no app directory is found, you'll be prompted to confirm whether to add to the current directory
  • Project templates are added to the current directory or specified --target-path
  • Model configurations are automatically injected based on available API keys in your environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_GENERATIVE_AI_API_KEY)

inkeep update

Update the Inkeep CLI to the latest version from npm.

inkeep update

Options:

  • --check - Check for updates without installing
  • --force - Force update even if already on latest version

How it Works:

The update command automatically:

  1. Detects Package Manager: Identifies which package manager (npm, pnpm, bun, or yarn) was used to install the CLI globally
  2. Checks Version: Compares your current version with the latest available on npm
  3. Updates CLI: Executes the appropriate update command for your package manager
  4. Displays Changelog: Shows a link to the changelog for release notes

Examples:

# Check if an update is available (no installation)
inkeep update --check

# Update to latest version (with confirmation prompt)
inkeep update

# Force reinstall current version
inkeep update --force

# Skip confirmation prompt (useful for CI/CD)
inkeep update --force

Output Example:

📦 Version Information:
  • Current version: 0.22.3
  • Latest version:  0.23.0

📖 Changelog:
  • https://github.com/inkeep/agents/blob/main/agents-cli/CHANGELOG.md

🔍 Detected package manager: pnpm

✅ Updated to version 0.23.0

Troubleshooting:

If you encounter permission errors, try running with elevated permissions:

# For npm, pnpm, yarn
sudo inkeep update

# For bun
sudo -E bun add -g @inkeep/agents-cli@latest

Package Manager Detection:

The CLI automatically detects which package manager you used by checking global package installations:

  • npm: Checks npm list -g @inkeep/agents-cli
  • pnpm: Checks pnpm list -g @inkeep/agents-cli
  • bun: Checks bun pm ls -g
  • yarn: Checks yarn global list

If automatic detection fails, the CLI will prompt you to select your package manager.

Configuration File

The CLI uses a configuration file (typically inkeep.config.ts) to store settings:

import { defineConfig } from "@inkeep/agents-cli/config";

export default defineConfig({
  tenantId: "your-tenant-id",
  agentsManageApiUrl: "http://localhost:3002",
  agentsRunApiUrl: "http://localhost:3003",
});

Configuration Priority

Effective resolution order:

  1. Command-line flags (highest)
  2. Environment variables (override config values)
  3. inkeep.config.ts values

Environment Variables

The CLI and SDK respect the following environment variables:

  • INKEEP_TENANT_ID - Tenant identifier
  • INKEEP_AGENTS_MANAGE_API_URL - Management API base URL
  • INKEEP_AGENTS_RUN_API_URL - Run API base URL
  • INKEEP_ENV - Environment name for credentials loading during inkeep push
  • INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET - Optional bearer for Manage API (advanced)
  • INKEEP_AGENTS_RUN_API_BYPASS_SECRET - Optional bearer for Run API (advanced)

Troubleshooting

Project Not Found:

  • Projects are automatically managed based on your tenantId
  • inkeep push will create resources as needed

Getting Help

For additional help with any command:

inkeep [command] --help

For issues or feature requests, visit: GitHub Issues

Add External Agents to your AgentGet started with the Visual Agent Builder

On this page

Overview
Installation
Global Options
Commands
inkeep init
inkeep push
Project Discovery and Structure
Push Behavior
inkeep pull
TypeScript Updates (Default)
Model Configuration
Validation Process
inkeep list-agents
inkeep dev
inkeep config
inkeep config get [key]
inkeep config set <key> <value>
inkeep config list
inkeep add
inkeep update
Configuration File
Configuration Priority
Environment Variables
Troubleshooting
Getting Help