Skip to content

Commands

init - Register a New Workspace

Registers a new workspace with kortex-cli, making it available for agent launch and configuration.

Usage

kortex-cli 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 KORTEX_CLI_DEFAULT_RUNTIME is not set)
  • --agent, -a <name> - Agent to use for the workspace (required if KORTEX_CLI_DEFAULT_AGENT is not set)
  • --workspace-configuration <path> - Directory for workspace configuration files (default: <sources-directory>/.kortex)
  • --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)
  • --verbose, -v - Show detailed output including all workspace information
  • --output, -o <format> - Output format (supported: json)
  • --storage <path> - Storage directory for kortex-cli data (default: $HOME/.kortex-cli)

Examples

Register the current directory: 

kortex-cli init --runtime fake --agent claude
Output: a1b2c3d4e5f6... (workspace ID)

Register a specific directory: 

kortex-cli init /path/to/myproject --runtime fake --agent claude

Register with a custom name: 

kortex-cli init /path/to/myproject --runtime fake --agent claude --name "my-awesome-project"

Register with a custom project identifier: 

kortex-cli init /path/to/myproject --runtime fake --agent claude --project "my project"

Register with custom configuration location: 

kortex-cli init /path/to/myproject --runtime fake --agent claude --workspace-configuration /path/to/config

View detailed output: 

kortex-cli init --runtime fake --agent claude --verbose
Output: 
Registered workspace:
  ID: a1b2c3d4e5f6...
  Name: myproject
  Agent: claude
  Sources directory: /absolute/path/to/myproject
  Configuration directory: /absolute/path/to/myproject/.kortex

JSON output (default - ID only): 

kortex-cli init /path/to/myproject --runtime fake --agent claude --output json
Output: 
{
  "id": "a1b2c3d4e5f6..."
}

JSON output with verbose flag (full workspace details): 

kortex-cli init /path/to/myproject --runtime fake --agent claude --output json --verbose
Output: 
{
  "id": "a1b2c3d4e5f6...",
  "name": "myproject",
  "agent": "claude",
  "paths": {
    "source": "/absolute/path/to/myproject",
    "configuration": "/absolute/path/to/myproject/.kortex"
  }
}

JSON output with short flags: 

kortex-cli init -r fake -a claude -o json -v

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, kortex-cli automatically appends an increment (-2, -3, etc.) to ensure uniqueness

Examples: 

# First workspace in /home/user/project
kortex-cli init /home/user/project --runtime fake --agent claude
# Name: "project"

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

# Third workspace with the same name
kortex-cli init /tmp/project --runtime fake --agent claude --name "project"
# Name: "project-3"

Project Detection

When registering a workspace, kortex-cli 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
kortex-cli init /home/user/kortex-cli --runtime fake --agent claude
# Project: https://github.com/kortex-hub/kortex-cli/

# Workspace in subdirectory
kortex-cli init /home/user/kortex-cli/pkg/git --runtime fake --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
kortex-cli init /home/user/local-repo --runtime fake --agent claude
# Project: /home/user/local-repo

# Workspace in subdirectory
kortex-cli init /home/user/local-repo/pkg/utils --runtime fake --agent claude
# Project: /home/user/local-repo/pkg/utils

3. Non-git directory

The project is the workspace source directory path:

Example - Regular directory: 

kortex-cli init /tmp/workspace --runtime fake --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 KORTEX_CLI_DEFAULT_RUNTIME environment variable
  • Agent is required: You must specify an agent using either the --agent flag or the KORTEX_CLI_DEFAULT_AGENT environment variable
  • 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
  • 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 (.kortex) 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)
  • 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 kortex-cli. Also available as the shorter alias list.

Usage

kortex-cli workspace list [flags]
kortex-cli list [flags]

Flags

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

Examples

List all workspaces (human-readable format): 

kortex-cli workspace list
Output: 
ID: a1b2c3d4e5f6...
  Name: myproject
  Agent: claude
  Sources: /absolute/path/to/myproject
  Configuration: /absolute/path/to/myproject/.kortex

ID: f6e5d4c3b2a1...
  Name: another-project
  Agent: goose
  Sources: /absolute/path/to/another-project
  Configuration: /absolute/path/to/another-project/.kortex

Use the short alias: 

kortex-cli list

List workspaces in JSON format: 

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

List with short flag: 

kortex-cli 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 ID. Also available as the shorter alias start.

Usage

kortex-cli workspace start ID [flags]
kortex-cli start ID [flags]

Arguments

  • ID - The unique identifier of the workspace to start (required)

Flags

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

Examples

Start a workspace by ID: 

kortex-cli workspace start a1b2c3d4e5f6...
Output: a1b2c3d4e5f6... (ID of started workspace)

Use the short alias: 

kortex-cli start a1b2c3d4e5f6...

View workspace IDs before starting: 

# First, list all workspaces to find the ID
kortex-cli list

# Then start the desired workspace
kortex-cli start a1b2c3d4e5f6...

JSON output: 

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

JSON output with short flag: 

kortex-cli start a1b2c3d4e5f6... -o json

Error Handling

Workspace not found (text format): 

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

Workspace not found (JSON format): 

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

Notes

  • The workspace ID is required and can be obtained using the workspace list or list command
  • Starting a workspace launches its associated runtime instance
  • Upon successful start, the command outputs the ID of the started workspace
  • 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 ID. Also available as the shorter alias stop.

Usage

kortex-cli workspace stop ID [flags]
kortex-cli stop ID [flags]

Arguments

  • ID - The unique identifier of the workspace to stop (required)

Flags

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

Examples

Stop a workspace by ID: 

kortex-cli workspace stop a1b2c3d4e5f6...
Output: a1b2c3d4e5f6... (ID of stopped workspace)

Use the short alias: 

kortex-cli stop a1b2c3d4e5f6...

View workspace IDs before stopping: 

# First, list all workspaces to find the ID
kortex-cli list

# Then stop the desired workspace
kortex-cli stop a1b2c3d4e5f6...

JSON output: 

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

JSON output with short flag: 

kortex-cli stop a1b2c3d4e5f6... -o json

Error Handling

Workspace not found (text format): 

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

Workspace not found (JSON format): 

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

Notes

  • The workspace ID is required and can be obtained using the workspace list or list command
  • Stopping a workspace stops its associated runtime instance
  • Upon successful stop, the command outputs the ID of the stopped workspace
  • 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

kortex-cli workspace terminal ID [COMMAND...] [flags]
kortex-cli terminal ID [COMMAND...] [flags]

Arguments

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

Flags

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

Examples

Connect using the default agent command: 

kortex-cli workspace terminal a1b2c3d4e5f6...

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

Use the short alias: 

kortex-cli terminal a1b2c3d4e5f6...

Run a bash shell: 

kortex-cli terminal a1b2c3d4e5f6... bash

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

kortex-cli terminal a1b2c3d4e5f6... -- bash -c 'echo hello'

The -- separator tells kortex-cli 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 kortex-cli.

List workspaces and connect to a running one: 

# First, list all workspaces to find the ID
kortex-cli list

# Start a workspace if it's not running
kortex-cli start a1b2c3d4e5f6...

# Then connect with a terminal
kortex-cli terminal a1b2c3d4e5f6...

Error Handling

Workspace not found: 

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

Workspace not running: 

kortex-cli terminal a1b2c3d4e5f6...
Output: 
Error: instance is not running (current state: created)

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

kortex-cli start a1b2c3d4e5f6...
kortex-cli 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
  • The workspace ID is required and 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 kortex-cli 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 ID. Also available as the shorter alias remove.

Usage

kortex-cli workspace remove ID [flags]
kortex-cli remove ID [flags]

Arguments

  • ID - The unique identifier of the workspace to remove (required)

Flags

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

Examples

Remove a workspace by ID: 

kortex-cli workspace remove a1b2c3d4e5f6...
Output: a1b2c3d4e5f6... (ID of removed workspace)

Use the short alias: 

kortex-cli remove a1b2c3d4e5f6...

View workspace IDs before removing: 

# First, list all workspaces to find the ID
kortex-cli list

# Then remove the desired workspace
kortex-cli remove a1b2c3d4e5f6...

JSON output: 

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

JSON output with short flag: 

kortex-cli remove a1b2c3d4e5f6... -o json

Error Handling

Workspace not found (text format): 

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

Workspace not found (JSON format): 

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

Notes

  • The workspace ID is required and can be obtained using the workspace list or list command
  • Removing a workspace only unregisters it from kortex-cli; it does not delete any files from the sources or configuration directories
  • If the workspace ID is not found, the command will fail with a helpful error message
  • Upon successful removal, the command outputs the ID of the removed workspace
  • 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