Skip to content

commands

commands

Every subcommand terok-shield exposes — arguments, handler, and help text.

The COMMANDS tuple is the single source of truth consumed by both the standalone CLI and the terok integration layer. Handler functions accept (shield, container?, **kwargs) and print to stdout, making them reusable across different CLI frontends.

CommandDef and ArgDef are re-exported from terok_util — the unified vocabulary every sibling package shares. Shield-specific flags (needs_container, standalone_only) ride along in CommandDef.extras; the shield CLI dispatcher reads them via the needs_container and standalone_only helpers defined below.

COMMANDS = (CommandDef(name='status', help='Show shield configuration overview', handler=_handle_status, args=(ArgDef(name='container', nargs='?', help='Container name — prints firewall state (up/down/disengaged/offline/error)'),)), CommandDef(name='prepare', help='Prepare shield and print podman flags', extras=_NEEDS_CTR_STANDALONE, args=(ArgDef(name='--profiles', type=_csv_list, help="Override default profiles (comma-separated, e.g. 'dev,pypi')"), ArgDef(name='--json', action='store_true', dest='output_json', help='JSON output'))), CommandDef(name='run', help='Launch a shielded container via podman', extras=_NEEDS_CTR_STANDALONE, args=(ArgDef(name='--profiles', type=_csv_list, help="Override default profiles (comma-separated, e.g. 'dev,pypi')"),)), CommandDef(name='resolve', help='Resolve DNS profiles and cache IPs', extras=_NEEDS_CTR_STANDALONE, args=(ArgDef(name='--force', action='store_true', help='Bypass cache freshness'),)), CommandDef(name='allow', help='Live-allow a domain or IP for a container', handler=_handle_allow, extras=_NEEDS_CTR, args=(ArgDef(name='target', help='Domain name or IP address to allow'),)), CommandDef(name='deny', help='Live-deny a domain or IP for a container', handler=_handle_deny, extras=_NEEDS_CTR, args=(ArgDef(name='target', help='Domain name or IP address to deny'),)), CommandDef(name='down', help='Switch container to bypass mode (accept-all + log)', handler=_handle_down, extras=_NEEDS_CTR, args=(_CONTAINER_ID_ARG, ArgDef(name='--all', action='store_true', dest='allow_all', help='Also allow private-range traffic'))), CommandDef(name='up', help='Restore deny-all mode for a container', handler=_handle_up, extras=_NEEDS_CTR, args=(_CONTAINER_ID_ARG,)), CommandDef(name='quarantine', help='Total network blackout (drop all, log dropped traffic)', handler=_handle_quarantine, extras=_NEEDS_CTR), CommandDef(name='rules', help='Show current nft rules for a container', handler=_handle_rules, extras=_NEEDS_CTR), CommandDef(name='watch', help='Stream shield events — DNS blocks, audit log, NFLOG packets (requires dnsmasq tier)', handler=_handle_watch, extras=_NEEDS_CTR), CommandDef(name='simple-clearance', help='Terminal clearance fallback — prompts operator for each blocked connection (no D-Bus)', handler=_handle_simple_clearance, extras=_NEEDS_CTR), CommandDef(name='logs', help='Show audit log entries', handler=_handle_logs, extras=_NEEDS_CTR, args=(ArgDef(name='-n', type=int, default=50, help='Number of recent entries'),)), CommandDef(name='profiles', help='List available shield profiles', handler=_handle_profiles), CommandDef(name='setup', help='Install global OCI hooks for restart persistence', extras=_STANDALONE), CommandDef(name='check-environment', help='Check podman environment for compatibility issues', handler=_handle_check_environment), CommandDef(name='preview', help='Show ruleset that would be applied', handler=_handle_preview, args=(ArgDef(name='--down', action='store_true', help='Show bypass ruleset'), ArgDef(name='--all', action='store_true', dest='allow_all', help='Omit private-range reject rules (requires --down)')))) module-attribute

needs_container(cmd)

Whether cmd requires a container positional arg.

Stored in CommandDef.extras rather than as a first-class field so the registry uses the unified terok-util vocabulary across siblings.

Source code in src/terok_shield/commands.py 
43
44
45
46
47
48
49
50
51
def needs_container(cmd: CommandDef) -> bool:
    """Whether *cmd* requires a ``container`` positional arg.

    Stored in
    [`CommandDef.extras`][terok_util.cli_types.CommandDef.extras]
    rather than as a first-class field so the registry uses the
    unified terok-util vocabulary across siblings.
    """
    return bool(cmd.extras.get("needs_container", False))

standalone_only(cmd)

Whether cmd is only available in the standalone CLI, not via terok.

Stored in CommandDef.extras — see needs_container.

Source code in src/terok_shield/commands.py 
54
55
56
57
58
59
60
61
def standalone_only(cmd: CommandDef) -> bool:
    """Whether *cmd* is only available in the standalone CLI, not via terok.

    Stored in
    [`CommandDef.extras`][terok_util.cli_types.CommandDef.extras] —
    see [`needs_container`][terok_shield.commands.needs_container].
    """
    return bool(cmd.extras.get("standalone_only", False))