Scenarios

Managing Workspaces from a UI or Programmatically¶

This scenario demonstrates how to manage workspaces programmatically using JSON output, which is ideal for UIs, scripts, or automation tools. All commands support the --output json (or -o json) flag for machine-readable output.

Step 1: Check existing workspaces

$ kortex-cli workspace list -o json

{
  "items": []
}

Exit code: 0 (success, but no workspaces registered)

Step 2: Register a new workspace

$ kortex-cli init /path/to/project --runtime fake --agent claude -o json

{
  "id": "2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea"
}

Exit code: 0 (success)

Step 3: Register with verbose output to get full details

$ kortex-cli init /path/to/another-project --runtime fake --agent claude -o json -v

{
  "id": "f6e5d4c3b2a1098765432109876543210987654321098765432109876543210a",
  "name": "another-project",
  "agent": "claude",
  "paths": {
    "source": "/absolute/path/to/another-project",
    "configuration": "/absolute/path/to/another-project/.kortex"
  }
}

Exit code: 0 (success)

Step 4: List all workspaces

$ kortex-cli workspace list -o json

{
  "items": [
    {
      "id": "2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea",
      "name": "project",
      "agent": "claude",
      "paths": {
        "source": "/absolute/path/to/project",
        "configuration": "/absolute/path/to/project/.kortex"
      }
    },
    {
      "id": "f6e5d4c3b2a1098765432109876543210987654321098765432109876543210a",
      "name": "another-project",
      "agent": "claude",
      "paths": {
        "source": "/absolute/path/to/another-project",
        "configuration": "/absolute/path/to/another-project/.kortex"
      }
    }
  ]
}

Exit code: 0 (success)

Step 5: Start a workspace

$ kortex-cli workspace start 2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea -o json

{
  "id": "2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea"
}

Exit code: 0 (success)

Step 6: Stop a workspace

$ kortex-cli workspace stop 2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea -o json

{
  "id": "2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea"
}

Exit code: 0 (success)

Step 7: Remove a workspace

$ kortex-cli workspace remove 2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea -o json

{
  "id": "2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea"
}

Exit code: 0 (success)

Step 8: Verify removal

$ kortex-cli workspace list -o json

{
  "items": [
    {
      "id": "f6e5d4c3b2a1098765432109876543210987654321098765432109876543210a",
      "name": "another-project",
      "agent": "claude",
      "paths": {
        "source": "/absolute/path/to/another-project",
        "configuration": "/absolute/path/to/another-project/.kortex"
      }
    }
  ]
}

Exit code: 0 (success)

Error Handling¶

All errors are returned in JSON format when using --output json, with the error written to stdout (not stderr) and a non-zero exit code.

Error: Non-existent directory

$ kortex-cli init /tmp/no-exist --runtime fake --agent claude -o json

{
  "error": "sources directory does not exist: /tmp/no-exist"
}

Exit code: 1 (error)

Error: Workspace not found

$ kortex-cli workspace remove unknown-id -o json

{
  "error": "workspace not found: unknown-id"
}

Exit code: 1 (error)

Best Practices for Programmatic Usage¶

Always check the exit code to determine success (0) or failure (non-zero)
Parse stdout for JSON output in both success and error cases
Use verbose mode with init (-v) when you need full workspace details immediately after creation
Handle both success and error JSON structures in your code:
Success responses have specific fields (e.g., id, items, name, paths)
Error responses always have an error field

Example script pattern:

#!/bin/bash

# Register a workspace
output=$(kortex-cli init /path/to/project --runtime fake --agent claude -o json)
exit_code=$?

if [ $exit_code -eq 0 ]; then
    workspace_id=$(echo "$output" | jq -r '.id')
    echo "Workspace created: $workspace_id"
else
    error_msg=$(echo "$output" | jq -r '.error')
    echo "Error: $error_msg"
    exit 1
fi