Skip to content

Commit 7bc1e90

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 cd53588 commit 7bc1e90

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
@@ -648,6 +648,37 @@ sudo awf --env-all --allow-domains api.github.com \
648648

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

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

653684
### No Internationalized Domains

0 commit comments

Comments
 (0)