Skip to content

Commands

info - Display Information About kdn

Displays version, available agents, and supported runtimes.

Usage

kdn info [flags]

Flags

  • --output, -o <format> - Output format (supported: json)
  • --storage <path> - Storage directory for kdn data (default: $HOME/.kdn)

Examples

Show info (human-readable format): 

kdn info
Output: 
Version: 0.3.0
Agents: claude
Runtimes: fake, podman

Show info in JSON format: 

kdn info --output json
Output: 
{
  "version": "0.3.0",
  "agents": [
    "claude"
  ],
  "runtimes": [
    "fake",
    "podman"
  ]
}

Show info using short flag: 

kdn info -o json

Notes

  • Agents are discovered from runtimes that support agent configuration (e.g., the Podman runtime reports agents from its configuration files)
  • Runtimes are listed based on availability in the current environment (e.g., the Podman runtime only appears if the podman CLI is installed)
  • JSON error handling: When --output json is used, errors are written to stdout (not stderr) in JSON format, and the CLI exits with code 1. Always check the exit code to determine success/failure

init - Register a New Workspace

Registers a new workspace with kdn, making it available for agent launch and configuration.

Usage

kdn init [sources-directory] [flags]

Arguments

  • sources-directory - Path to the directory containing your project source files (optional, defaults to current directory .)

Flags

  • --runtime, -r <type> - Runtime to use for the workspace (required if KDN_DEFAULT_RUNTIME is not set)
  • --agent, -a <name> - Agent to use for the workspace (required if KDN_DEFAULT_AGENT is not set)
  • --model, -m <id> - Model ID to configure for the agent (optional, uses agent's default if not specified)
  • --workspace-configuration <path> - Directory for workspace configuration files (default: <sources-directory>/.kaiden)
  • --name, -n <name> - Human-readable name for the workspace (default: generated from sources directory)
  • --project, -p <identifier> - Custom project identifier to override auto-detection (default: auto-detected from git repository or source directory)
  • --start - Start the workspace after registration (can also be set via KDN_INIT_AUTO_START environment variable)
  • --verbose, -v - Show detailed output including all workspace information
  • --output, -o <format> - Output format (supported: json)
  • --show-logs - Show stdout and stderr from runtime commands (cannot be combined with --output json)
  • --storage <path> - Storage directory for kdn data (default: $HOME/.kdn)

Examples

Register the current directory: 

kdn init --runtime podman --agent claude
Output: a1b2c3d4e5f6... (workspace ID)

Register a specific directory: 

kdn init /path/to/myproject --runtime podman --agent claude

Register with a custom name: 

kdn init /path/to/myproject --runtime podman --agent claude --name "my-awesome-project"

Register with a custom project identifier: 

kdn init /path/to/myproject --runtime podman --agent claude --project "my project"

Register with custom configuration location: 

kdn init /path/to/myproject --runtime podman --agent claude --workspace-configuration /path/to/config

Register with a specific model: 

kdn init /path/to/myproject --runtime podman --agent claude --model claude-sonnet-4-20250514

Register and start immediately: 

kdn init /path/to/myproject --runtime podman --agent claude --start
Output: a1b2c3d4e5f6... (workspace ID, workspace is now running)

Register and start using environment variable: 

export KDN_INIT_AUTO_START=1
kdn init /path/to/myproject --runtime podman --agent claude
Output: a1b2c3d4e5f6... (workspace ID, workspace is now running)

View detailed output: 

kdn init --runtime podman --agent claude --verbose
Output: 
Registered workspace:
  ID: a1b2c3d4e5f6...
  Name: myproject
  Project: /absolute/path/to/myproject
  Agent: claude
  Sources directory: /absolute/path/to/myproject
  Configuration directory: /absolute/path/to/myproject/.kaiden
  State: stopped

JSON output (default - ID only): 

kdn init /path/to/myproject --runtime podman --agent claude --output json
Output: 
{
  "id": "a1b2c3d4e5f6..."
}

JSON output with verbose flag (full workspace details): 

kdn init /path/to/myproject --runtime podman --agent claude --output json --verbose
Output: 
{
  "id": "a1b2c3d4e5f6...",
  "name": "myproject",
  "agent": "claude",
  "project": "/absolute/path/to/myproject",
  "state": "stopped",
  "paths": {
    "source": "/absolute/path/to/myproject",
    "configuration": "/absolute/path/to/myproject/.kaiden"
  }
}

JSON output with short flags: 

kdn init -r fake -a claude -o json -v

Show runtime command output (e.g., image build logs): 

kdn init --runtime podman --agent claude --show-logs

Workspace Naming

  • If --name is not provided, the name is automatically generated from the last component of the sources directory path
  • If a workspace with the same name already exists, kdn automatically appends an increment (-2, -3, etc.) to ensure uniqueness

Examples: 

# First workspace in /home/user/project
kdn init /home/user/project --runtime podman --agent claude
# Name: "project"

# Second workspace with the same directory name
kdn init /home/user/another-location/project --runtime podman --agent claude --name "project"
# Name: "project-2"

# Third workspace with the same name
kdn init /tmp/project --runtime podman --agent claude --name "project"
# Name: "project-3"

Project Detection

When registering a workspace, kdn automatically detects and stores a project identifier. This allows grouping workspaces that belong to the same project, even across different branches, forks, or subdirectories.

The project is determined using the following rules:

1. Git repository with remote URL

The project is the repository remote URL (without .git suffix) plus the workspace's relative path within the repository:

  • At repository root: https://github.com/user/repo/
  • In subdirectory: https://github.com/user/repo/sub/path

Remote priority: 1. upstream remote is checked first (useful for forks) 2. origin remote is used if upstream doesn't exist 3. If neither exists, falls back to local repository path (see below)

Example - Fork with upstream: 

# Repository setup:
# upstream: https://github.com/kortex-hub/kortex-cli.git
# origin:   https://github.com/myuser/kortex-cli.git (fork)

# Workspace at repository root
kdn init /home/user/kortex-cli --runtime podman --agent claude
# Project: https://github.com/kortex-hub/kortex-cli/

# Workspace in subdirectory
kdn init /home/user/kortex-cli/pkg/git --runtime podman --agent claude
# Project: https://github.com/kortex-hub/kortex-cli/pkg/git

This ensures all forks and branches of the same upstream repository are grouped together.

2. Git repository without remote

The project is the repository root directory path plus the workspace's relative path:

  • At repository root: /home/user/my-local-repo
  • In subdirectory: /home/user/my-local-repo/sub/path

Example - Local repository: 

# Workspace at repository root
kdn init /home/user/local-repo --runtime podman --agent claude
# Project: /home/user/local-repo

# Workspace in subdirectory
kdn init /home/user/local-repo/pkg/utils --runtime podman --agent claude
# Project: /home/user/local-repo/pkg/utils

3. Non-git directory

The project is the workspace source directory path:

Example - Regular directory: 

kdn init /tmp/workspace --runtime podman --agent claude
# Project: /tmp/workspace

Benefits:

  • Cross-branch grouping: Workspaces in different git worktrees or branches of the same repository share the same project
  • Fork grouping: Forks reference the upstream repository, grouping all contributors working on the same project
  • Subdirectory support: Monorepo subdirectories are tracked with their full path for precise identification
  • Custom override: Use --project flag to manually group workspaces under a custom identifier (e.g., "client-project")
  • Future filtering: The project field enables filtering and grouping commands (e.g., list all workspaces for a specific project)

Notes

  • Runtime is required: You must specify a runtime using either the --runtime flag or the KDN_DEFAULT_RUNTIME environment variable
  • Agent is required: You must specify an agent using either the --agent flag or the KDN_DEFAULT_AGENT environment variable
  • Model is optional: Use --model to specify a model ID for the agent. The flag takes precedence over any model defined in the agent's default settings files (~/.kdn/config/<agent>/). If not provided, the agent uses its default model or the one configured in settings. All agents support model configuration: Claude (via .claude/settings.json), Goose (via config.yaml), and Cursor (via .cursor/cli-config.json)
  • Project auto-detection: The project identifier is automatically detected from git repository information or source directory path. Use --project flag to override with a custom identifier
  • Auto-start: Use the --start flag or set KDN_INIT_AUTO_START=1 to automatically start the workspace after registration, combining init and start into a single operation
  • All directory paths are converted to absolute paths for consistency
  • The workspace ID is a unique identifier generated automatically
  • Workspaces can be listed using the workspace list command
  • The default configuration directory (.kaiden) is created inside the sources directory unless specified otherwise
  • JSON output format is useful for scripting and automation
  • Without --verbose, JSON output returns only the workspace ID
  • With --verbose, JSON output includes full workspace details (ID, name, agent, paths)
  • Use --show-logs to display the full stdout and stderr from runtime commands (e.g., podman build output during image creation)
  • JSON error handling: When --output json is used, errors are written to stdout (not stderr) in JSON format, and the CLI exits with code 1. Always check the exit code to determine success/failure

workspace list - List All Registered Workspaces

Lists all workspaces that have been registered with kdn. Also available as the shorter alias list.

Usage

kdn workspace list [flags]
kdn list [flags]

Flags

  • --output, -o <format> - Output format (supported: json)
  • --storage <path> - Storage directory for kdn data (default: $HOME/.kdn)

Examples

List all workspaces (human-readable format): 

kdn workspace list
Output: 
ID: a1b2c3d4e5f6...
  Name: myproject
  Project: /absolute/path/to/myproject
  Agent: claude
  Sources: /absolute/path/to/myproject
  Configuration: /absolute/path/to/myproject/.kaiden
  State: running

ID: f6e5d4c3b2a1...
  Name: another-project
  Project: /absolute/path/to/another-project
  Agent: goose
  Sources: /absolute/path/to/another-project
  Configuration: /absolute/path/to/another-project/.kaiden
  State: stopped

Use the short alias: 

kdn list

List workspaces in JSON format: 

kdn workspace list --output json
Output: 
{
  "items": [
    {
      "id": "a1b2c3d4e5f6...",
      "name": "myproject",
      "agent": "claude",
      "project": "/absolute/path/to/myproject",
      "state": "running",
      "paths": {
        "source": "/absolute/path/to/myproject",
        "configuration": "/absolute/path/to/myproject/.kaiden"
      }
    },
    {
      "id": "f6e5d4c3b2a1...",
      "name": "another-project",
      "agent": "goose",
      "project": "/absolute/path/to/another-project",
      "state": "stopped",
      "paths": {
        "source": "/absolute/path/to/another-project",
        "configuration": "/absolute/path/to/another-project/.kaiden"
      }
    }
  ]
}

List with short flag: 

kdn list -o json

Notes

  • When no workspaces are registered, the command displays "No workspaces registered"
  • The JSON output format is useful for scripting and automation
  • All paths are displayed as absolute paths for consistency
  • JSON error handling: When --output json is used, errors are written to stdout (not stderr) in JSON format, and the CLI exits with code 1. Always check the exit code to determine success/failure

workspace start - Start a Workspace

Starts a registered workspace by its name or ID. Also available as the shorter alias start.

Usage

kdn workspace start NAME|ID [flags]
kdn start NAME|ID [flags]

Arguments

  • NAME|ID - The workspace name or unique identifier (required)

Flags

  • --output, -o <format> - Output format (supported: json)
  • --show-logs - Show stdout and stderr from runtime commands (cannot be combined with --output json)
  • --storage <path> - Storage directory for kdn data (default: $HOME/.kdn)

Examples

Start a workspace by ID: 

kdn workspace start a1b2c3d4e5f6...
Output: a1b2c3d4e5f6... (ID of started workspace)

Start a workspace by name: 

kdn workspace start my-project
Output: a1b2c3d4e5f6... (ID of started workspace)

Use the short alias: 

kdn start my-project

View workspace names and IDs before starting: 

# First, list all workspaces to find the name or ID
kdn list

# Then start the desired workspace (using either name or ID)
kdn start my-project

JSON output: 

kdn workspace start a1b2c3d4e5f6... --output json
Output: 
{
  "id": "a1b2c3d4e5f6..."
}

JSON output with short flag: 

kdn start a1b2c3d4e5f6... -o json

Show runtime command output: 

kdn workspace start a1b2c3d4e5f6... --show-logs

Error Handling

Workspace not found (text format): 

kdn start invalid-id
Output: 
Error: workspace not found: invalid-id
Use 'workspace list' to see available workspaces

Workspace not found (JSON format): 

kdn start invalid-id --output json
Output: 
{
  "error": "workspace not found: invalid-id"
}

Notes

  • You can specify the workspace using either its name or ID (both can be obtained using the workspace list or list command)
  • The command always outputs the workspace ID, even when started by name
  • Starting a workspace launches its associated runtime instance
  • The workspace runtime state is updated to reflect that it's running
  • JSON output format is useful for scripting and automation
  • When using --output json, errors are also returned in JSON format for consistent parsing
  • JSON error handling: When --output json is used, errors are written to stdout (not stderr) in JSON format, and the CLI exits with code 1. Always check the exit code to determine success/failure

workspace stop - Stop a Workspace

Stops a running workspace by its name or ID. Also available as the shorter alias stop.

Usage

kdn workspace stop NAME|ID [flags]
kdn stop NAME|ID [flags]

Arguments

  • NAME|ID - The workspace name or unique identifier (required)

Flags

  • --output, -o <format> - Output format (supported: json)
  • --show-logs - Show stdout and stderr from runtime commands (cannot be combined with --output json)
  • --storage <path> - Storage directory for kdn data (default: $HOME/.kdn)

Examples

Stop a workspace by ID: 

kdn workspace stop a1b2c3d4e5f6...
Output: a1b2c3d4e5f6... (ID of stopped workspace)

Stop a workspace by name: 

kdn workspace stop my-project
Output: a1b2c3d4e5f6... (ID of stopped workspace)

Use the short alias: 

kdn stop my-project

View workspace names and IDs before stopping: 

# First, list all workspaces to find the name or ID
kdn list

# Then stop the desired workspace (using either name or ID)
kdn stop my-project

JSON output: 

kdn workspace stop a1b2c3d4e5f6... --output json
Output: 
{
  "id": "a1b2c3d4e5f6..."
}

JSON output with short flag: 

kdn stop a1b2c3d4e5f6... -o json

Show runtime command output: 

kdn workspace stop a1b2c3d4e5f6... --show-logs

Error Handling

Workspace not found (text format): 

kdn stop invalid-id
Output: 
Error: workspace not found: invalid-id
Use 'workspace list' to see available workspaces

Workspace not found (JSON format): 

kdn stop invalid-id --output json
Output: 
{
  "error": "workspace not found: invalid-id"
}

Notes

  • You can specify the workspace using either its name or ID (both can be obtained using the workspace list or list command)
  • The command always outputs the workspace ID, even when stopped by name
  • Stopping a workspace stops its associated runtime instance
  • The workspace runtime state is updated to reflect that it's stopped
  • JSON output format is useful for scripting and automation
  • When using --output json, errors are also returned in JSON format for consistent parsing
  • JSON error handling: When --output json is used, errors are written to stdout (not stderr) in JSON format, and the CLI exits with code 1. Always check the exit code to determine success/failure

workspace terminal - Connect to a Running Workspace

Connects to a running workspace with an interactive terminal session. Also available as the shorter alias terminal.

Usage

kdn workspace terminal NAME|ID [COMMAND...] [flags]
kdn terminal NAME|ID [COMMAND...] [flags]

Arguments

  • NAME|ID - The workspace name or unique identifier (required)
  • COMMAND... - Optional command to execute instead of the default agent command

Flags

  • --storage <path> - Storage directory for kdn data (default: $HOME/.kdn)

Examples

Connect using the default agent command (by ID): 

kdn workspace terminal a1b2c3d4e5f6...

Connect using the default agent command (by name): 

kdn workspace terminal my-project

This starts an interactive session with the default agent (typically Claude Code) inside the running workspace container.

Use the short alias: 

kdn terminal my-project

Run a bash shell: 

kdn terminal my-project bash

Run a command with flags (use -- to prevent kdn from parsing them): 

kdn terminal a1b2c3d4e5f6... -- bash -c 'echo hello'

The -- separator tells kdn to stop parsing flags and pass everything after it directly to the container. This is useful when your command includes flags that would otherwise be interpreted by kdn.

List workspaces and connect to a running one: 

# First, list all workspaces to find the ID
kdn list

# Start a workspace if it's not running
kdn start a1b2c3d4e5f6...

# Then connect with a terminal
kdn terminal a1b2c3d4e5f6...

Error Handling

Workspace not found: 

kdn terminal invalid-id
Output: 
Error: workspace not found: invalid-id
Use 'workspace list' to see available workspaces

Workspace not running: 

kdn terminal a1b2c3d4e5f6...
Output: 
Error: instance is not running (current state: created)

In this case, you need to start the workspace first: 

kdn start a1b2c3d4e5f6...
kdn terminal a1b2c3d4e5f6...

Notes

  • The workspace must be in a running state before you can connect to it. Use workspace start to start a workspace first
  • You can specify the workspace using either its name or ID (both can be obtained using the workspace list or list command)
  • By default (when no command is provided), the runtime uses the terminal_command from the agent's configuration file
  • For example, if the workspace was created with --agent claude, it will use the command defined in claude.json (typically ["claude"])
  • This ensures you connect directly to the configured agent
  • You can override the default by providing a custom command (e.g., bash, python, or any executable available in the container)
  • Use the -- separator when your command includes flags to prevent kdn from trying to parse them
  • The terminal session is fully interactive with stdin/stdout/stderr connected to your terminal
  • The command execution happens inside the workspace's container/runtime environment
  • JSON output is not supported for this command as it's inherently interactive
  • Runtime support: The terminal command requires the runtime to implement the Terminal interface. The Podman runtime supports this using podman exec -it

workspace remove - Remove a Workspace

Removes a registered workspace by its name or ID. Also available as the shorter alias remove.

Usage

kdn workspace remove NAME|ID [flags]
kdn remove NAME|ID [flags]

Arguments

  • NAME|ID - The workspace name or unique identifier (required)

Flags

  • --force, -f - Stop the workspace if it is running before removing it
  • --output, -o <format> - Output format (supported: json)
  • --show-logs - Show stdout and stderr from runtime commands (cannot be combined with --output json)
  • --storage <path> - Storage directory for kdn data (default: $HOME/.kdn)

Examples

Remove a workspace by ID: 

kdn workspace remove a1b2c3d4e5f6...
Output: a1b2c3d4e5f6... (ID of removed workspace)

Remove a workspace by name: 

kdn workspace remove my-project
Output: a1b2c3d4e5f6... (ID of removed workspace)

Use the short alias: 

kdn remove my-project

View workspace names and IDs before removing: 

# First, list all workspaces to find the name or ID
kdn list

# Then remove the desired workspace (using either name or ID)
kdn remove my-project

Remove a running workspace (stops it first): 

kdn workspace remove a1b2c3d4e5f6... --force
Output: a1b2c3d4e5f6... (ID of removed workspace)

JSON output: 

kdn workspace remove a1b2c3d4e5f6... --output json
Output: 
{
  "id": "a1b2c3d4e5f6..."
}

JSON output with short flag: 

kdn remove a1b2c3d4e5f6... -o json

Show runtime command output: 

kdn workspace remove a1b2c3d4e5f6... --show-logs

Error Handling

Workspace not found (text format): 

kdn remove invalid-id
Output: 
Error: workspace not found: invalid-id
Use 'workspace list' to see available workspaces

Workspace not found (JSON format): 

kdn remove invalid-id --output json
Output: 
{
  "error": "workspace not found: invalid-id"
}

Removing a running workspace without --force:

Attempting to remove a running workspace without --force will fail because the runtime refuses to remove a running instance. Stop the workspace first, or use --force:

# Stop first, then remove
kdn stop a1b2c3d4e5f6...
kdn remove a1b2c3d4e5f6...

# Or remove in one step
kdn remove a1b2c3d4e5f6... --force

Notes

  • You can specify the workspace using either its name or ID (both can be obtained using the workspace list or list command)
  • The command always outputs the workspace ID, even when removed by name
  • Removing a workspace only unregisters it from kdn; it does not delete any files from the sources or configuration directories
  • If the workspace name or ID is not found, the command will fail with a helpful error message
  • Use --force to automatically stop a running workspace before removing it; without this flag, removing a running workspace will fail
  • Tab completion for this command suggests only non-running workspaces by default; when --force is specified, all workspaces are suggested
  • JSON output format is useful for scripting and automation
  • When using --output json, errors are also returned in JSON format for consistent parsing
  • JSON error handling: When --output json is used, errors are written to stdout (not stderr) in JSON format, and the CLI exits with code 1. Always check the exit code to determine success/failure