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

# 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 add`

Add a new template to the project

Add project templates or MCP server templates to your Inkeep project. Templates provide pre-configured setups for common use cases.

inkeep add [template] [options]

Arguments:

template - Template name to add

Options:

--project <template> - Project template to add
--mcp <template> - MCP template to add
--target-path <path> - Target path to add the template to
--local-prefix <path_prefix> - Use local templates from the given path prefix
--config <path> - Path to configuration file

Examples:

Add a project template

inkeep add --project docs-assistant

Add an MCP server template

inkeep add --mcp filesystem

Add template to specific path

inkeep add --project docs-assistant --target-path ./agents

`inkeep config`

Manage Inkeep configuration

Manage your Inkeep configuration file. Get, set, or list configuration values.

Subcommands:

inkeep config get
inkeep config set
inkeep config list

`inkeep config get`

Get configuration value(s)

Get a specific configuration value or all values if no key is provided.

inkeep config get [key] [options]

Arguments:

key - Configuration key to get (optional, shows all if omitted)

Options:

--config <path> - Path to configuration file

Examples:

Get all config values

inkeep config get

Get specific config value

inkeep config get tenantId

`inkeep config set`

Set a configuration value

Set a configuration value in the config file.

inkeep config set <key> <value> [options]

Arguments:

key(required) - Configuration key to set
value(required) - Value to set

Options:

--config <path> - Path to configuration file

Examples:

Set tenant ID

inkeep config set tenantId my-tenant-id

`inkeep config list`

List all configuration values

Display all configuration values from the config file.

inkeep config list [options]

Options:

--config <path> - Path to configuration file

Examples:

List all config values

inkeep config list

`inkeep dev`

Start the Inkeep dashboard server

Start the Inkeep dashboard server for local development. The dashboard provides a visual interface for testing and debugging your agents.

inkeep dev [options]

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
--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
--open-browser - Open the browser

Examples:

Start dashboard on default port

inkeep dev

Start on custom port

inkeep dev --port 8080

Build for production

inkeep dev --build

Start and open browser

inkeep dev --open-browser

`inkeep init`

Initialize a new Inkeep project (runs cloud onboarding wizard by default)

Initialize a new Inkeep configuration file in your project. By default, runs the cloud onboarding wizard. Use --local for self-hosted mode.

inkeep init [path] [options]

Arguments:

path - Directory path to initialize the project in

Options:

--local - Use local/self-hosted mode instead of cloud onboarding
--no-interactive - Skip interactive prompts (default: true)
--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

Local/self-hosted mode

inkeep init --local

`inkeep list-agent`

List all available agents for a specific project

List all agents configured for a specific project. Requires a project ID to be specified.

inkeep list-agent [options]

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

Examples:

List agents for a project

inkeep list-agent --project my-project-id

`inkeep login`

Authenticate with Inkeep Cloud

Authenticate with Inkeep Cloud using browser-based OAuth. Credentials are stored securely in your profile.

inkeep login [options]

Options:

--profile <name> - Profile to authenticate (defaults to active profile)

Examples:

inkeep login

inkeep login --profile staging

`inkeep logout`

Log out of Inkeep Cloud

Log out of Inkeep Cloud and remove stored credentials from your profile.

inkeep logout [options]

Options:

--profile <name> - Profile to log out (defaults to active profile)

Examples:

Logout from active profile

inkeep logout

Logout from specific profile

inkeep logout --profile staging

`inkeep profile`

Manage CLI profiles for connecting to different remotes

Manage named CLI profiles for multiple remotes, credentials, and environments. Profiles are stored in ~/.inkeep/profiles.yaml. A default 'cloud' profile points to hosted endpoints.

Examples:

Create a local profile and switch to it

inkeep profile add local && inkeep profile use local

Subcommands:

inkeep profile list
inkeep profile add
inkeep profile use
inkeep profile current
inkeep profile remove

`inkeep profile list`

List all profiles

Display all configured profiles and indicate the currently active profile.

inkeep profile list

Examples:

List all profiles

inkeep profile list

`inkeep profile add`

Add a new profile

Add a new named profile. If no name is provided, you will be prompted to enter one.

inkeep profile add [name]

Arguments:

name - Name for the new profile

Examples:

Add a new profile interactively

inkeep profile add

Add a named profile

inkeep profile add staging

`inkeep profile use`

Set the active profile

Set a profile as the currently active profile. All subsequent commands will use this profile.

inkeep profile use <name>

Arguments:

name(required) - Profile name to activate

Examples:

Switch to staging profile

inkeep profile use staging

`inkeep profile current`

Display the active profile details

Display detailed information about the currently active profile including remote URLs and authentication state.

inkeep profile current

Examples:

Show current profile

inkeep profile current

`inkeep profile remove`

Remove a profile

Remove a named profile. Cannot remove the currently active profile.

inkeep profile remove <name>

Arguments:

name(required) - Profile name to remove

Examples:

Remove staging profile

inkeep profile remove staging

`inkeep pull`

Pull project configuration with clean, efficient code generation

Pull project configuration from the server and generate local TypeScript files. This command fetches your Agent configurations and creates well-structured code that can be edited and pushed back.

inkeep pull [options]

Options:

--project <project-id> - Project ID to pull (or path to project directory). If in project directory, validates against local project ID.
--config <path> - Path to configuration file
--profile <name> - Profile to use for remote URLs and authentication
--env <environment> - Environment file to generate (development, staging, production). Defaults to development
--json - Output project data as JSON instead of generating files
--debug - Enable debug logging
--verbose - Enable verbose logging
--force - Force regeneration even if no changes detected
--introspect - Completely regenerate all files from scratch (no comparison needed)
--all - Pull all projects for current tenant
--tag <tag> - Use tagged config file (e.g., --tag prod loads prod.__inkeep.config.ts__)
--quiet - Suppress profile/config logging

Examples:

Pull current project

inkeep pull

Pull specific project

inkeep pull --project my-project-id

Pull all projects for tenant

inkeep pull --all

Force regeneration of all files

inkeep pull --force

Output as JSON

inkeep pull --json

`inkeep push`

Push a project configuration to the backend

Push a project containing Agent configurations to your server. This command deploys your entire multi-agent project, including all Agents, Sub Agents, and tools. The most common workflow is to run `inkeep push` from inside a project directory. A project directory is identified by having an `index.ts` file that exports a project object (with `__type = "project"`).

inkeep push [options]

Options:

--project <project-id> - Project ID or path to project directory
--config <path> - Path to configuration file
--profile <name> - Profile to use for remote URLs and authentication
--tenant-id <id> - Override tenant ID
--agents-manage-api-url <url> - Override agents manage API URL
--agents-run-api-url <url> - Override agents run API URL
--env <environment> - Environment to use for credential resolution (e.g., development, production)
--json - Generate project data JSON file instead of pushing to backend
--all - Push all projects found in current directory tree
--tag <tag> - Use tagged config file (e.g., --tag prod loads prod.__inkeep.config.ts__)
--quiet - Suppress profile/config logging

Examples:

Push project from current directory

inkeep push

Push specific project directory

inkeep push --project ./my-project

Push all projects in current directory tree

inkeep push --all

Push with development environment credentials

inkeep push --env development

Generate project JSON without pushing

inkeep push --json

Use a named profile

inkeep push --profile staging

`inkeep status`

Show current profile, authentication state, and remote URLs

Display the current profile configuration including authentication state, remote API URLs, and tenant information.

inkeep status [options]

Options:

--profile <name> - Profile to show status for (defaults to active profile)

Examples:

Show status for active profile

inkeep status

Show status for specific profile

inkeep status --profile staging

See also: login, logout, profile, whoami

`inkeep update`

Update @inkeep/agents-cli to the latest version

Check for and install updates to the Inkeep CLI. Use --check to see if updates are available without installing.

inkeep update [options]

Options:

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

Examples:

Update to latest version

inkeep update

Check for updates

inkeep update --check

Force reinstall

inkeep update --force

`inkeep whoami`

Display current authentication status (alias for status)

Display current authentication status. This is an alias for the status command.

inkeep whoami

Examples:

Show current auth status

inkeep whoami

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",
  agentsManageApi: {
    url: "http://localhost:3002",
  },
  agentsRunApi: {
    url: "http://localhost:3003",
  },
});

Configuration Priority

Effective resolution order:

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

Environment Variables

The CLI and SDK respect the following environment variables:

Variable	Description
`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

inkeep add

inkeep config

inkeep config get

inkeep config set

inkeep config list

inkeep dev

inkeep init

inkeep list-agent

inkeep login

inkeep logout

inkeep profile

inkeep profile list

inkeep profile add

inkeep profile use

inkeep profile current

inkeep profile remove

inkeep pull

inkeep push

inkeep status

inkeep update

inkeep whoami

On this page

`inkeep add`

`inkeep config`

`inkeep config get`

`inkeep config set`

`inkeep config list`

`inkeep dev`

`inkeep init`

`inkeep list-agent`

`inkeep login`

`inkeep logout`

`inkeep profile`

`inkeep profile list`

`inkeep profile add`

`inkeep profile use`

`inkeep profile current`

`inkeep profile remove`

`inkeep pull`

`inkeep push`

`inkeep status`

`inkeep update`

`inkeep whoami`