> ## Documentation Index
> Fetch the complete documentation index at: https://toolkit.astralsolutions.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate Toolkit with AI Coding Agents and CI/CD Pipelines

> Every Toolkit command supports --json structured output. Use it to feed port checks, disk reports, and proxy state into AI agents and CI/CD scripts.

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:

```bash theme={null}
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.

<Note>
  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.
</Note>

## Example JSON Outputs

### `toolkit ports list --json`

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

```bash theme={null}
toolkit ports list --json
```

```json theme={null}
[
  {
    "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:

```bash theme={null}
toolkit clean scan ~/projects --json
```

```json theme={null}
{
  "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:

```bash theme={null}
toolkit proxy list --json
```

```json theme={null}
[
  {
    "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:

```bash theme={null}
toolkit autostart status --json
```

```json theme={null}
{
  "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:

```bash theme={null}
toolkit ports analyze --json
```

```json theme={null}
{
  "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:**

1. The agent calls `toolkit ports list --json` to get all occupied ports.
2. It parses the response to find a free port in the `3000–4000` range.
3. It generates a configuration file (e.g., `vite.config.ts` or `.env`) with the chosen port pre-populated.
4. It calls `toolkit proxy add my-new-service <port>` to register the proxy route.
5. It reports back to the developer: *"Started your service on port 3001, accessible at [http://my-new-service.localhost](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.

<CardGroup cols={2}>
  <Card title="Port Awareness" icon="network-wired">
    Call `toolkit ports list --json` before scaffolding any new service to detect available ports and avoid conflicts automatically.
  </Card>

  <Card title="Environment State" icon="chart-bar">
    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.
  </Card>
</CardGroup>

## CI/CD Integration

<Steps>
  <Step title="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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    # 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-`).
  </Step>
</Steps>

## 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:**

```bash theme={null}
# Kill the process on port 3000
toolkit ports kill 3000 --json
```

**Find all Node.js processes listening on any port:**

```bash theme={null}
toolkit ports list --json | grep '"processName": "node"'
```

**Use `jq` to extract just the port numbers in use:**

```bash theme={null}
toolkit ports list --json | jq '[.[].port]'
# Output: [3000, 5173, 8000, 5432]
```

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

```bash theme={null}
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:**

```bash theme={null}
toolkit clean scan ~/projects --json | jq '[.targets[] | select(.orphaned == true)]'
```