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

# toolkit hosts — Non-Destructive Hosts File Management

> toolkit hosts list, add, and remove commands — safely add and remove domain-to-IP mappings in your system hosts file using isolated labeled blocks.

The `toolkit hosts` command group lets you add, remove, and inspect custom domain-to-IP mappings in your system hosts file. Unlike tools that write directly into the body of the file, Toolkit uses a **labeled isolation block** to contain every entry it manages. Your existing hosts file content is never touched — Toolkit's entries live inside a clearly delimited section that you can inspect at any time, and the block is removed cleanly when all managed entries are gone.

***

## toolkit hosts list

Lists all domain entries currently managed by Toolkit, along with a count of unmanaged system entries that exist outside the block.

**Syntax**

```bash theme={null}
toolkit hosts list [options]
```

**Options**

| Option   | Type    | Default | Description                                         |
| :------- | :------ | :------ | :-------------------------------------------------- |
| `--json` | boolean | `false` | Emit the full hosts file status as structured JSON. |

**Examples**

```bash theme={null}
# Display managed and unmanaged entries in a human-readable table
toolkit hosts list

# Output structured JSON (useful for scripts and CI pipelines)
toolkit hosts list --json
```

***

## toolkit hosts add

Adds a domain-to-IP mapping inside the Toolkit-managed block of your system hosts file. If the domain already exists in the managed block, the entry is updated. The rest of your hosts file is not modified.

**Syntax**

```bash theme={null}
toolkit hosts add <domain> [ip] [options]
```

**Arguments**

| Argument   | Type   | Required | Description                                                       |
| :--------- | :----- | :------- | :---------------------------------------------------------------- |
| `<domain>` | string | Yes      | The domain name to map (e.g. `my-app.local`).                     |
| `[ip]`     | string | No       | The IP address to resolve the domain to. Defaults to `127.0.0.1`. |

**Options**

| Option   | Type    | Default | Description                                   |
| :------- | :------ | :------ | :-------------------------------------------- |
| `--json` | boolean | `false` | Emit the operation result as structured JSON. |

**Examples**

```bash theme={null}
# Add a domain pointing to the default loopback address (127.0.0.1)
toolkit hosts add my-app.local

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

# Add a domain and receive a JSON response
toolkit hosts add my-app.local --json
```

***

## toolkit hosts remove

Removes a managed domain from the Toolkit isolation block in your system hosts file. If no managed entries remain after the removal, Toolkit cleans up the block entirely.

**Syntax**

```bash theme={null}
toolkit hosts remove <domain> [options]
```

**Arguments**

| Argument   | Type   | Required | Description                   |
| :--------- | :----- | :------- | :---------------------------- |
| `<domain>` | string | Yes      | The managed domain to remove. |

**Options**

| Option   | Type    | Default | Description                                   |
| :------- | :------ | :------ | :-------------------------------------------- |
| `--json` | boolean | `false` | Emit the operation result as structured JSON. |

**Examples**

```bash theme={null}
# Remove a previously added domain
toolkit hosts remove my-app.local

# Remove a domain and receive a JSON response
toolkit hosts remove api.local --json
```

***

## Isolation mechanism

Toolkit never edits the native content of your hosts file. Instead, it inserts a self-contained block delimited by two marker comments. Everything outside this block remains exactly as you left it.

After running `toolkit hosts add my-app.local` and `toolkit hosts add api.local 192.168.1.50`, your hosts file will contain a section that looks like this:

```bash theme={null}
# (your existing hosts file content above — untouched)

# >>> ALL-IN-ONE-TOOLKIT BEGIN >>>
# Custom domains managed by all-in-one-toolkit. Do not edit this block manually.
127.0.0.1        my-app.local
192.168.1.50     api.local
# <<< ALL-IN-ONE-TOOLKIT END <<<

# (your existing hosts file content below — untouched)
```

When you remove all managed entries, Toolkit deletes the block entirely, leaving your hosts file in a clean state.

<Warning>
  On Windows and some Linux distributions, writing to the hosts file requires administrator or root privileges. If Toolkit cannot write to the file, it will report the error and prompt you to re-run the command with elevated permissions (e.g. `sudo toolkit hosts add ...` on macOS/Linux, or running your terminal as Administrator on Windows).
</Warning>