Integrate Toolkit with AI Coding Agents and CI/CD Pipelines

Every toolkit command accepts a --json flag that switches its output from human-readable text to structured, machine-parseable JSON. This single flag transforms the CLI into a first-class data source for AI coding agents, CI/CD pipelines, shell scripts, and any automation workflow that needs reliable information about your local development environment. The exit code continues to reflect success or failure regardless of output format, so your existing error-handling logic works without changes.

The `--json` Flag

Add --json to any Toolkit command to receive structured output instead of the formatted table or prose you’d see in a terminal:

toolkit <command> [subcommand] [args] --json

The flag is available on every command across every module: ports, clean, proxy, hosts, autostart, and daemon. The shape of the JSON object is consistent and documented per-command — making it straightforward to build typed interfaces around in any language.

JSON output is written to stdout. Error and warning messages are written to stderr so they never pollute the JSON stream. Your parsing logic can safely read stdout without filtering out diagnostic messages.

Example JSON Outputs

`toolkit ports list --json`

Returns an array of every port currently in use, with process metadata for each entry:

toolkit ports list --json

[
  {
    "port": 3000,
    "protocol": "TCP",
    "pid": 48291,
    "processName": "node",
    "localAddress": "127.0.0.1"
  },
  {
    "port": 5173,
    "protocol": "TCP",
    "pid": 49104,
    "processName": "vite",
    "localAddress": "127.0.0.1"
  },
  {
    "port": 8000,
    "protocol": "TCP",
    "pid": 50237,
    "processName": "python3",
    "localAddress": "0.0.0.0"
  },
  {
    "port": 5432,
    "protocol": "TCP",
    "pid": 312,
    "processName": "postgres",
    "localAddress": "127.0.0.1"
  }
]

`toolkit clean scan ~/projects --json`

Returns a summary of all discovered dependency and virtual environment directories, along with the total recoverable disk space:

toolkit clean scan ~/projects --json

{
  "scannedPath": "/home/user/projects",
  "depth": 5,
  "totalSize": "3.12 GB",
  "totalSizeBytes": 3350274048,
  "targets": [
    {
      "path": "/home/user/projects/old-landing/node_modules",
      "type": "node_modules",
      "sizeBytes": 888012800,
      "size": "847 MB",
      "orphaned": true
    },
    {
      "path": "/home/user/projects/api-v1/node_modules",
      "type": "node_modules",
      "sizeBytes": 327155712,
      "size": "312 MB",
      "orphaned": false
    },
    {
      "path": "/home/user/projects/ml-experiment/venv",
      "type": "venv",
      "sizeBytes": 1181116006,
      "size": "1.1 GB",
      "orphaned": true
    }
  ]
}

`toolkit proxy list --json`

Returns all active proxy routes registered on the reverse proxy:

toolkit proxy list --json

[
  {
    "subdomain": "frontend",
    "targetPort": 3000,
    "url": "http://frontend.localhost"
  },
  {
    "subdomain": "api",
    "targetPort": 4000,
    "url": "http://api.localhost"
  },
  {
    "subdomain": "docs",
    "targetPort": 8000,
    "url": "http://docs.localhost"
  }
]

`toolkit autostart status --json`

Returns the current autostart configuration for the running platform:

toolkit autostart status --json

{
  "enabled": true,
  "platform": "linux",
  "mode": "daemon_notify",
  "targetUrl": "http://toolkit.localhost",
  "entryPath": "~/.config/autostart/all-in-one-toolkit.desktop"
}

`toolkit ports analyze --json`

Returns a diagnostic report of the current port landscape, including detected conflicts between processes and any ports that may collide with well-known services:

toolkit ports analyze --json

{
  "scannedAt": "2024-07-15T10:32:00.000Z",
  "totalPorts": 12,
  "conflicts": [
    {
      "port": 3000,
      "pids": [48291, 51034],
      "processNames": ["node", "node"],
      "description": "Two processes are bound to the same port."
    }
  ],
  "warnings": [
    {
      "port": 8080,
      "pid": 49800,
      "processName": "python3",
      "description": "Port commonly used by HTTP proxies — verify this is intentional."
    }
  ],
  "recommendations": [
    "Kill PID 51034 on port 3000 to resolve the conflict.",
    "Consider moving the Python server on port 8080 to an unprivileged port above 8000."
  ]
}

Using with AI Coding Agents

AI agents like Cursor, GitHub Copilot Workspace, or custom LLM-powered tools can call toolkit ports list --json to understand the state of your local environment before taking action. This gives the agent accurate, real-time data rather than relying on assumptions or stale configuration files. Example workflow — agent scaffolding a new service:

The agent calls toolkit ports list --json to get all occupied ports.
It parses the response to find a free port in the 3000–4000 range.
It generates a configuration file (e.g., vite.config.ts or .env) with the chosen port pre-populated.
It calls toolkit proxy add my-new-service <port> to register the proxy route.
It reports back to the developer: “Started your service on port 3001, accessible at http://my-new-service.localhost.”

This eliminates the “what port should I use?” back-and-forth and prevents conflicts with services already running on your machine.

Port Awareness

Call toolkit ports list --json before scaffolding any new service to detect available ports and avoid conflicts automatically.

Environment State

Use toolkit proxy list --json and toolkit autostart status --json to give your agent a full picture of the current dev environment before generating code.

CI/CD Integration

Check for port conflicts before starting tests

At the beginning of your CI job, run a port conflict analysis to catch environment issues before your test suite starts:

toolkit ports analyze --json

The JSON output includes a conflicts array. If it is non-empty, your tests are likely to fail due to port collisions — fail fast here instead of debugging mysterious test failures later.

Parse the JSON output and fail the build if conflicts exist

Use jq (or any JSON parser in your CI environment) to assert that no conflicts exist before proceeding:

CONFLICTS=$(toolkit ports analyze --json | jq '.conflicts | length')

if [ "$CONFLICTS" -gt "0" ]; then
  echo "Port conflicts detected. Aborting test run."
  exit 1
fi

echo "No port conflicts. Proceeding with tests."

This pattern works in GitHub Actions, GitLab CI, CircleCI, Jenkins, or any shell-based pipeline.

Clean up proxy routes after the test run

After your tests complete, remove any proxy routes that were registered during the run to leave the environment clean for the next job:

# List all active routes as JSON
toolkit proxy list --json

# Remove each route registered during the test run
toolkit proxy remove test-frontend
toolkit proxy remove test-api

If you registered routes dynamically, parse the toolkit proxy list --json output and remove every route whose subdomain matches your CI naming convention (e.g., prefixed with test-).

Shell Scripting

The --json flag makes it easy to compose Toolkit with standard Unix tools. Here are a few practical shell snippets: Kill the process on a specific port:

# Kill the process on port 3000
toolkit ports kill 3000 --json

Find all Node.js processes listening on any port:

toolkit ports list --json | grep '"processName": "node"'

Use jq to extract just the port numbers in use:

toolkit ports list --json | jq '[.[].port]'
# Output: [3000, 5173, 8000, 5432]

Check total recoverable disk space and alert if it exceeds 5 GB:

BYTES=$(toolkit clean scan ~/projects --json | jq '.totalSizeBytes')
THRESHOLD=$((5 * 1024 * 1024 * 1024))

if [ "$BYTES" -gt "$THRESHOLD" ]; then
  echo "Warning: more than 5 GB of dev environments detected. Run toolkit clean purge."
fi

List all orphaned environments only:

toolkit clean scan ~/projects --json | jq '[.targets[] | select(.orphaned == true)]'

Getting Started

Core Features

Web Dashboard

Guides

Integrate Toolkit with AI Coding Agents and CI/CD Pipelines

The `--json` Flag

Example JSON Outputs

`toolkit ports list --json`

`toolkit clean scan ~/projects --json`

`toolkit proxy list --json`

`toolkit autostart status --json`

`toolkit ports analyze --json`

Using with AI Coding Agents

Port Awareness

Environment State

CI/CD Integration

Shell Scripting

​The --json Flag

​Example JSON Outputs

​toolkit ports list --json

​toolkit clean scan ~/projects --json

​toolkit proxy list --json

​toolkit autostart status --json

​toolkit ports analyze --json

​Using with AI Coding Agents

Port Awareness

Environment State

​CI/CD Integration

​Shell Scripting

The `--json` Flag

Example JSON Outputs

`toolkit ports list --json`

`toolkit clean scan ~/projects --json`

`toolkit proxy list --json`

`toolkit autostart status --json`

`toolkit ports analyze --json`

Using with AI Coding Agents

CI/CD Integration

Shell Scripting