Skip to content

docs: fix inaccuracies in CLI reference #1611

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mossaka merged 2 commits into from
Apr 2, 2026
Merged

docs: fix inaccuracies in CLI reference #1611

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4a698b6
Initial plan
Copilot Apr 2, 2026
bfa2104
docs: fix inaccuracies in CLI reference
Copilot Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs-site/src/content/docs/reference/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ awf [options] -- <command>
| `--exclude-env <name>` | string | `[]` | Exclude a variable from `--env-all` passthrough (repeatable) |
| `-v, --mount <host:container[:mode]>` | string | `[]` | Volume mount (repeatable) |
| `--container-workdir <dir>` | string | User home | Working directory inside container |
| `--dns-servers <servers>` | string | `8.8.8.8,8.8.4.4` | Trusted DNS servers (comma-separated) |
| `--dns-servers <servers>` | string | Auto-detected | Trusted DNS servers (comma-separated; auto-detected from host, falls back to `8.8.8.8,8.8.4.4`) |
| `--proxy-logs-dir <path>` | string | — | Directory to save Squid proxy logs to |
| `--enable-host-access` | flag | `false` | Enable access to host services via host.docker.internal |
| `--allow-host-ports <ports>` | string | `80,443` | Ports to allow when using --enable-host-access |
Expand Down Expand Up @@ -169,7 +169,7 @@ Set logging verbosity.
Keep containers and configuration files after command exits for debugging.

:::note
Requires manual cleanup: `docker stop awf-squid awf-copilot && docker network rm awf-net`
Requires manual cleanup: `docker stop awf-squid awf-agent && docker network rm awf-net`
Copy link

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The manual cleanup command stops containers but doesn’t remove them; docker network rm awf-net will fail if the (even stopped) containers are still attached to the network. Consider switching to docker rm -f awf-squid awf-agent (or docker stop ... && docker rm ...) before removing the network, consistent with other docs in the repo.

Suggested change
Requires manual cleanup: `docker stop awf-squid awf-agent && docker network rm awf-net`
Requires manual cleanup: `docker rm -f awf-squid awf-agent && docker network rm awf-net`

Copilot uses AI. Check for mistakes.
:::

### `--tty`
Expand Down Expand Up @@ -246,9 +246,11 @@ Mount host directories into container. Format: `host_path:container_path[:ro|rw]
- Host path must exist
- Mode: `ro` (read-only) or `rw` (read-write)

**Default mounts:**
- Host filesystem at `/host` (read-only)
- User home directory (read-write)
**Default mounts (selective bind mounts, not a blanket host FS mount):**
- System binaries (`/usr`, `/bin`, `/sbin`, `/lib`, `/lib64`, `/opt`, `/sys`, `/dev`) at `/host` (read-only)
Copy link

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The wording “System binaries (...) at /host” is a bit inaccurate: these are bind-mounted under /host/<dir> (e.g. /usr → /host/usr, /bin → /host/bin, etc.), not mounted as a single filesystem at /host. Rephrase to “under /host” (or spell out the /host/usr, /host/bin, … paths) to avoid confusion.

Suggested change
- System binaries (`/usr`, `/bin`, `/sbin`, `/lib`, `/lib64`, `/opt`, `/sys`, `/dev`) at `/host` (read-only)
- System binaries (`/usr`, `/bin`, `/sbin`, `/lib`, `/lib64`, `/opt`, `/sys`, `/dev`) under `/host` (read-only)

Copilot uses AI. Check for mistakes.
- Workspace and `/tmp` (read-write)
- Whitelisted `$HOME` subdirs such as `.cache`, `.config`, `.local` (read-write)
- Select `/etc` files only — SSL certs, `passwd`, `group`, etc. (not `/etc/shadow`)

### `--container-workdir <dir>`

Expand All @@ -258,6 +260,8 @@ Working directory inside the container.

Comma-separated list of trusted DNS servers. DNS traffic is **only** allowed to these servers, preventing DNS-based data exfiltration. Both IPv4 and IPv6 addresses are supported.

If omitted, DNS servers are **auto-detected from host resolvers** (e.g., `/run/systemd/resolve/resolv.conf` or `/etc/resolv.conf`). Falls back to Google DNS (`8.8.8.8`, `8.8.4.4`) only if auto-detection fails.

```bash
# Use Cloudflare DNS
--dns-servers 1.1.1.1,1.0.0.1
Expand Down Expand Up @@ -285,7 +289,7 @@ sudo awf --enable-host-access --allow-domains host.docker.internal \
```

:::danger[Security Warning]
When `--enable-host-access` is enabled, containers can access services on the host machine. Use `--allow-host-ports` to restrict which ports can be accessed. Without port restrictions, all ports are allowed by default (this will change in a future version).
When `--enable-host-access` is enabled, containers can access services on the host machine. By default, only ports 80 and 443 are allowed. Use `--allow-host-ports` to allow additional ports.
:::

**See also:** [Host Access Configuration](/gh-aw-firewall/docs/usage/#host-access)
Expand All @@ -307,12 +311,8 @@ sudo awf --allow-domains localhost --allow-host-ports 3000 \
```

**Default behavior:**
- Without `--allow-host-ports`: Currently allows all ports (will default to 80,443 in future version)
- With `--allow-host-ports`: Only specified ports are allowed

:::tip[Best Practice]
Always explicitly specify `--allow-host-ports` to ensure consistent behavior across versions.
:::
- Without `--allow-host-ports`: Only ports 80 and 443 are allowed
Copy link

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section implies that omitting --allow-host-ports always results in only 80/443 being allowed, but there’s an important exception: when --allow-domains includes the special localhost keyword, the CLI auto-enables host access and auto-populates a default dev port list (3000, 4200, 5173, 8080, etc.) unless the user explicitly sets --allow-host-ports. Please document that exception here (or in the preceding --enable-host-access warning) so readers don’t get surprised by the broader default when using localhost.

Suggested change
- Without `--allow-host-ports`: Only ports 80 and 443 are allowed
- Without `--allow-host-ports`: Only ports 80 and 443 are allowed in the normal case
- Exception: If `--allow-domains` includes the special `localhost` keyword and you do not set `--allow-host-ports`, host access is auto-enabled and a default set of common development ports is allowed

Copilot uses AI. Check for mistakes.
- With `--allow-host-ports`: Only the specified ports are allowed

### `--proxy-logs-dir <path>`

Expand Down