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
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.
Options:
--no-interactive- Skip interactive path selection--config <path>- Path to use as template for new configuration
Examples:
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.
Options:
--project <project-id>- Project ID or path to project directory--env <environment>- Load environment-specific credentials fromenvironments/<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:
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:
Project Discovery and Structure
The inkeep push command follows this discovery process:
-
Config File Discovery: Searches for
inkeep.config.tsusing 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
--configflag
-
Workspace Structure: Expects this directory layout:
-
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
- All project directories containing
Push Behavior
When pushing, the CLI:
- Finds and loads configuration from
inkeep.config.tsat workspace root - Discovers all project directories containing
index.ts - Applies environment-specific settings if
--envis 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.
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:
- Automatic Detection: If your current directory contains an
index.tsfile that exports a project, the command automatically uses that project's ID - Current Directory Pull: Files are pulled directly to your current directory (no subdirectory is created)
- Conflict Prevention: If you specify
--projectwhile in a project directory, an error is shown to prevent confusion
Pull Modes:
| Scenario | Command | Behavior |
|---|---|---|
| In project directory | inkeep pull | ✅ Automatically detects project, pulls to current directory |
| In project directory | inkeep pull --project <id> | ❌ Error: Cannot specify --project when in project directory |
| Not in project directory | inkeep pull | Prompts for project ID, creates subdirectory |
| Not in project directory | inkeep 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:
- File Discovery: Recursively finds all
.tsfiles in your project (excludingenvironments/andnode_modules/) - Smart Categorization: Categorizes files as index, agents, Sub Agents, tools, or other files
- 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
- 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:
- Context Preservation: Maintains your existing code structure and patterns
- Selective Updates: Only updates relevant parts based on server configuration changes
- File-Specific Context: Each file type receives appropriate context (Agents get Agent data, Sub Agents get Sub Agent data, etc.)
Examples:
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 pushwithout errors - ✅ No data loss or corruption during the pull process
Validation Output:
If validation fails:
The CLI will display specific differences between the generated and expected data:
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
--jsonflag 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.
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:
inkeep dev
Start the Inkeep dashboard server, build for production, or export the Next.js project.
Note: This command requires
@inkeep/agents-manage-uito be installed for visual agents orchestration.
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:
inkeep config
Manage Inkeep configuration values.
Subcommands:
inkeep config get [key]
Get configuration value(s).
Options:
--config <path>- Path to configuration file--config-file-path <path>- Path to configuration file (deprecated, use --config)
Examples:
inkeep config set <key> <value>
Set a configuration value.
Options:
--config <path>- Path to configuration file--config-file-path <path>- Path to configuration file (deprecated, use --config)
Examples:
inkeep config list
List all configuration values.
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.
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:
Behavior:
- When adding an MCP template without
--target-path, the CLI automatically searches for anapps/mcp/appdirectory 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, orGOOGLE_GENERATIVE_AI_API_KEY)
inkeep update
Update the Inkeep CLI to the latest version from npm.
Options:
--check- Check for updates without installing--force- Force update even if already on latest version
How it Works:
The update command automatically:
- Detects Package Manager: Identifies which package manager (npm, pnpm, bun, or yarn) was used to install the CLI globally
- Checks Version: Compares your current version with the latest available on npm
- Updates CLI: Executes the appropriate update command for your package manager
- Displays Changelog: Shows a link to the changelog for release notes
Examples:
Output Example:
Troubleshooting:
If you encounter permission errors, try running with elevated permissions:
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:
Configuration Priority
Effective resolution order:
- Command-line flags (highest)
- Environment variables (override config values)
inkeep.config.tsvalues
Environment Variables
The CLI and SDK respect the following environment variables:
INKEEP_TENANT_ID- Tenant identifierINKEEP_AGENTS_MANAGE_API_URL- Management API base URLINKEEP_AGENTS_RUN_API_URL- Run API base URLINKEEP_ENV- Environment name for credentials loading duringinkeep pushINKEEP_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 pushwill create resources as needed
Getting Help
For additional help with any command:
For issues or feature requests, visit: GitHub Issues