> ## 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.

# Manage System Hosts File Entries Safely with Toolkit

> Add and remove custom domain-to-IP mappings in your hosts file via isolated labeled blocks, preserving existing entries on Windows, macOS, and Linux.

The Toolkit hosts manager lets you add custom domain-to-IP mappings — like routing `api.local` to `127.0.0.1` or `staging.internal` to a specific LAN address — without ever risking corruption of your existing system entries. Every change Toolkit makes is written inside clearly labeled delimiter blocks, keeping toolkit-managed rules fully isolated from anything that was already in your hosts file.

***

## Isolated Blocks

When you add an entry, Toolkit writes it inside a dedicated section:

```
# >>> ALL-IN-ONE-TOOLKIT BEGIN >>>
127.0.0.1   api.local
127.0.0.1   project.test
192.168.1.50  staging.internal
# <<< ALL-IN-ONE-TOOLKIT END <<<
```

Entries that existed in your hosts file before you ever used Toolkit are never touched. When you remove an entry or clear all toolkit rules, only the content between the delimiters changes — your pre-existing system rules stay exactly as they were.

<Warning>
  On **Windows** and some **Linux** configurations, your hosts file is owned by the system and requires elevated permissions to modify. Toolkit detects this automatically via the `canWrite` flag and will prompt you to approve a privilege escalation (UAC on Windows, `sudo` on Unix) before making any change. No modification is attempted silently.
</Warning>

***

## Hosts File Locations

| OS      | Hosts File Path                         |
| ------- | --------------------------------------- |
| Windows | `C:\Windows\System32\drivers\etc\hosts` |
| Linux   | `/etc/hosts`                            |
| macOS   | `/etc/hosts`                            |

***

## `toolkit hosts list`

Show every domain mapping Toolkit currently manages, plus a summary count of unmanaged entries already present in your system hosts file. The `managed` flag in each entry tells you whether Toolkit owns it.

```bash theme={null}
toolkit hosts list

toolkit hosts list --json
```

**Example terminal output:**

```
=== Hosts File (/etc/hosts) ===

Managed Toolkit Entries (3):
  127.0.0.1        api.local
  127.0.0.1        project.test
  192.168.1.50     staging.internal

Total unmanaged system entries: 8
```

***

## `toolkit hosts add <domain> [ip]`

Add a domain-to-IP mapping to the toolkit-managed block. If you omit the IP address, it defaults to `127.0.0.1` — the most common use case for local development domains.

```bash theme={null}
# Add a domain pointing to localhost (default IP: 127.0.0.1)
toolkit hosts add project.test

# Add a domain pointing to a custom IP address
toolkit hosts add api.local 192.168.1.50

# Add a domain and get a JSON confirmation
toolkit hosts add project.test --json
```

| Argument / Flag | Type      | Required | Description                                            |
| --------------- | --------- | -------- | ------------------------------------------------------ |
| `<domain>`      | `string`  | ✅        | Domain name to map (e.g., `api.local`, `my-app.test`). |
| `[ip]`          | `string`  | —        | Target IP address. Defaults to `127.0.0.1` if omitted. |
| `--json`        | `boolean` | —        | Emit the operation result as JSON.                     |

***

## `toolkit hosts remove <domain>`

Remove a specific Toolkit-managed domain mapping. Only entries inside the toolkit delimiter block are eligible for removal — you cannot accidentally delete system entries this way.

```bash theme={null}
# Remove a managed entry
toolkit hosts remove project.test

# Remove and confirm via JSON
toolkit hosts remove api.local --json
```

| Argument / Flag | Type      | Required | Description                        |
| --------------- | --------- | -------- | ---------------------------------- |
| `<domain>`      | `string`  | ✅        | The managed domain to remove.      |
| `--json`        | `boolean` | —        | Emit the operation result as JSON. |

***

## `--json` Output

**`toolkit hosts list --json`** emits a `HostsFileStatus` object containing both managed and unmanaged entries:

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

```json theme={null}
{
  "filePath": "/etc/hosts",
  "canWrite": true,
  "totalEntries": 11,
  "managedEntries": [
    {
      "ip": "127.0.0.1",
      "domain": "api.local",
      "comment": null,
      "managed": true
    },
    {
      "ip": "127.0.0.1",
      "domain": "project.test",
      "comment": null,
      "managed": true
    },
    {
      "ip": "192.168.1.50",
      "domain": "staging.internal",
      "comment": "staging server",
      "managed": true
    }
  ],
  "unmanagedEntries": [
    {
      "ip": "127.0.0.1",
      "domain": "localhost",
      "comment": null,
      "managed": false
    },
    {
      "ip": "::1",
      "domain": "localhost",
      "comment": null,
      "managed": false
    }
  ]
}
```

**`toolkit hosts add --json`** emits a confirmation object with the domain and resolved IP:

```bash theme={null}
toolkit hosts add api.local 192.168.1.50 --json
```

```json theme={null}
{
  "success": true,
  "domain": "api.local",
  "ip": "192.168.1.50"
}
```

**`toolkit hosts remove --json`** emits a confirmation object with the removed domain:

```bash theme={null}
toolkit hosts remove api.local --json
```

```json theme={null}
{
  "success": true,
  "domain": "api.local"
}
```