SlackStarSchedule a demo
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

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
  • --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 graphs, 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
│   ├── graphs/               # Agent graph 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 (graphs, 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 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

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

# Enable debug logging
inkeep pull --debug

# Override tenant ID when using custom API URL
inkeep pull --agents-manage-api-url https://api.example.com --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.

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:

  • --tenant-id <tenant-id> - Tenant ID
  • --agents-manage-api-url <url> - Agents manage API URL
  • --agents-run-api-url <url> - Agents run API URL
  • --config <path> - Path to configuration file
  • --config-file-path <path> - Path to configuration file (deprecated, use --config)

Examples:

# Interactive graph selection
inkeep chat

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

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

# Override tenant and API URLs
inkeep chat --tenant-id my-tenant --agents-manage-api-url https://api.example.com

inkeep list-graphs

List all available graphs for a specific project.

inkeep list-graphs --project <project-id>

Options:

  • --project <project-id> - Required. Project ID to list graphs 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 graphs for a specific project
inkeep list-graphs --project my-project

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

# Override tenant and API URL
inkeep list-graphs --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.

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 from the Inkeep Agents Cookbook.

inkeep add [template]

Options:

  • --target-path <path> - Target path to add the template to
  • --config <path> - Path to configuration file

Examples:

# Add a template
inkeep add weather-project

# Add template to specific path
inkeep add weather-project --target-path ./src/templates

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

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

Push and Pull WorkflowsUsing SigNoz for Observability

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
inkeep chat
inkeep list-graphs
inkeep dev
inkeep config
inkeep config get [key]
inkeep config set <key> <value>
inkeep config list
inkeep add
Configuration File
Configuration Priority
Environment Variables
Troubleshooting
Getting Help