Skip to content

Commit dfd40bd

Browse files
Mossakaclaude
andcommitted
docs: document flag validation constraints
Add "Flag Combinations and Constraints" section to usage.md documenting: - --skip-pull + --build-local incompatibility (with error message) - --allow-host-ports requires --enable-host-access (with error message) Fixes #496 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 40e46d6 commit dfd40bd

File tree

1 file changed

+31
-0
lines changed

1 file changed

+31
-0
lines changed

docs/usage.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -645,6 +645,37 @@ sudo awf --env-all --allow-domains api.github.com \
645645

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

648+
## Flag Combinations and Constraints
649+
650+
Certain flags have validation constraints that produce errors if violated.
651+
652+
### `--skip-pull` + `--build-local` = Error
653+
654+
These flags are incompatible. `--skip-pull` uses pre-downloaded images without pulling, while `--build-local` builds images from source (which requires pulling base images).
655+
656+
```bash
657+
# ❌ Error: incompatible flags
658+
sudo awf --skip-pull --build-local --allow-domains github.com -- your-command
659+
# Error: --skip-pull cannot be used with --build-local. Building images requires pulling base images from the registry.
660+
661+
# ✅ Correct: use one or the other
662+
sudo awf --skip-pull --allow-domains github.com -- your-command
663+
sudo awf --build-local --allow-domains github.com -- your-command
664+
```
665+
666+
### `--allow-host-ports` requires `--enable-host-access`
667+
668+
The `--allow-host-ports` flag restricts which host ports are accessible, so it only makes sense when host access is enabled.
669+
670+
```bash
671+
# ❌ Error: missing dependency flag
672+
sudo awf --allow-host-ports 3000,8080 --allow-domains github.com -- your-command
673+
# Error: --allow-host-ports requires --enable-host-access to be set
674+
675+
# ✅ Correct: include --enable-host-access
676+
sudo awf --enable-host-access --allow-host-ports 3000,8080 --allow-domains github.com -- your-command
677+
```
678+
648679
## Limitations
649680

650681
### No Internationalized Domains

0 commit comments

Comments
 (0)