CLI Reference

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

npm install -g @inkeep/agents-cli

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

Example:

# Interactive initialization
inkeep init

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

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

inkeep push

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

inkeep push

Options:

• --project <project-path> - Specify project directory by path or ID (defaults to current directory or searches for inkeep.config.ts)
• --env <environment> - Load environment-specific credentials from environments/<environment>.env.ts
• --agents-manage-api-url <url> - Override the management API URL from config
• --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 API URL
inkeep push --agents-manage-api-url https://api.example.com

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",
      },
    },
  },
});

Push behavior

When pushing, the CLI deploys your entire project (graphs, agents, tools) defined by your index.ts and configuration. After a successful push, it prints a short summary.

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-path> - Specify project directory by path or ID (defaults to current directory or searches for inkeep.config.ts)
• --agents-manage-api-url <url> - Override the management API URL from config
• --env <environment> - Override tenant ID when using custom API URL
• --json - Save project data as JSON file instead of updating TypeScript files

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, graphs, agents, tools, or other files
3. Context-Aware Updates: Updates each file with relevant context from the server:
   • Graph files: Updated with specific graph data
   • Agent files: Updated with specific 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 (graphs get graph data, agents get agent data, etc.)

Examples:

# Pull and update all project files from current directory
inkeep pull

# Pull specific project directory
inkeep pull --project ./my-project

# 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

# Override tenant ID when using custom API URL
inkeep pull --agents-manage-api-url https://api.example.com --env production

Model Configuration

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

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

inkeep chat

Start an interactive chat session with a graph.

inkeep chat [graph-id]

Options:

• --config-file-path <path> - Path to configuration file

Examples:

# Interactive graph selection
inkeep chat

# Chat with specific graph
inkeep chat my-graph-id

# Use a specific config file
inkeep chat --config-file-path ./inkeep.config.ts

inkeep list-graphs

List all available graphs for the current tenant.

inkeep list-graphs

Options:

• --config-file-path <path> - Path to configuration file

Examples:

# List graphs using config file
inkeep list-graphs

# List graphs using a specific config file
inkeep list-graphs --config-file-path ./inkeep.config.ts

inkeep dev

Start the Inkeep dashboard server.

inkeep dev

Options:

• --port <port> - Port to run the server on (default: 3000)
• --host <host> - Host to bind the server to (default: localhost)

Examples:

# Start with defaults
inkeep dev

# Custom port
inkeep dev --port 3001

# Bind to all interfaces
inkeep dev --host 0.0.0.0

inkeep config

Manage Inkeep configuration values.

Subcommands:

inkeep config get [key]

Get configuration value(s).

inkeep config get [key]

Options:

• --config-file-path <path> - Path to configuration file

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-file-path <path> - Path to configuration file

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-file-path <path> - Path to configuration file

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",
  projectId: "your-project-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_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:

• Ensure your projectId in inkeep.config.ts matches an existing project
• inkeep push will create the project automatically if it does not exist

Getting Help

For additional help with any command:

inkeep [command] --help

For issues or feature requests, visit: GitHub Issues