Skip to content

docs: document flag validation constraints #1230

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 1 commit into from
Mar 12, 2026
Merged

docs: document flag validation constraints #1230

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
31 changes: 31 additions & 0 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -648,6 +648,37 @@ sudo awf --env-all --allow-domains api.github.com \

For detailed documentation including security considerations, volume mounts, and troubleshooting, see [Chroot Mode](chroot-mode.md).

## Flag Combinations and Constraints

Certain flags have validation constraints that produce errors if violated.

### `--skip-pull` + `--build-local` = Error

These flags are incompatible. `--skip-pull` uses pre-downloaded images without pulling, while `--build-local` builds images from source (which requires pulling base images).

```bash
# ❌ Error: incompatible flags
sudo awf --skip-pull --build-local --allow-domains github.com -- your-command
# Error: --skip-pull cannot be used with --build-local. Building images requires pulling base images from the registry.

Comment on lines +660 to +663
Copy link

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

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

The documented CLI output here doesn’t match what the CLI actually prints. awf logs validation failures via logger.error(...), which prefixes output with [ERROR] and (for these cases) includes a leading ❌, not Error:. Please update the example output lines so they match the real CLI output format/message (including the ❌ prefix, and consider whether to include the [ERROR] prefix as well).

This issue also appears on line 671 of the same file.

Copilot uses AI. Check for mistakes.
# ✅ Correct: use one or the other
sudo awf --skip-pull --allow-domains github.com -- your-command
sudo awf --build-local --allow-domains github.com -- your-command
```

### `--allow-host-ports` requires `--enable-host-access`

The `--allow-host-ports` flag restricts which host ports are accessible, so it only makes sense when host access is enabled.

```bash
# ❌ Error: missing dependency flag
sudo awf --allow-host-ports 3000,8080 --allow-domains github.com -- your-command
# Error: --allow-host-ports requires --enable-host-access to be set

# ✅ Correct: include --enable-host-access
sudo awf --enable-host-access --allow-host-ports 3000,8080 --allow-domains github.com -- your-command
Comment on lines +675 to +679
Copy link

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

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

The “correct” example for --allow-host-ports uses --allow-domains github.com, but --allow-host-ports only affects access to host services (e.g., host.docker.internal / localhost). This example is valid syntactically, but it doesn’t demonstrate a working/meaningful host-access scenario; consider updating it to include --allow-domains host.docker.internal (or localhost) to align with the explanation and earlier examples in this doc.

Suggested change
sudo awf --allow-host-ports 3000,8080 --allow-domains github.com -- your-command
# Error: --allow-host-ports requires --enable-host-access to be set
# ✅ Correct: include --enable-host-access
sudo awf --enable-host-access --allow-host-ports 3000,8080 --allow-domains github.com -- your-command
sudo awf --allow-host-ports 3000,8080 --allow-domains host.docker.internal -- your-command
# Error: --allow-host-ports requires --enable-host-access to be set
# ✅ Correct: include --enable-host-access
sudo awf --enable-host-access --allow-host-ports 3000,8080 --allow-domains host.docker.internal -- your-command

Copilot uses AI. Check for mistakes.
```

## Limitations

### No Internationalized Domains
Expand Down
Loading