Skip to content

Cli

cli

CLI entry point for terok-executor.

Composes executor's own commands with sandbox's full tree (via SANDBOX_TREE) into a single CommandTree, exposed two ways:

  • Deep path — terok-executor sandbox <verb> reaches every sandbox verb verbatim, with executor's overlays applied where they exist (e.g. vault).
  • Shortcuts — terok-executor vault <verb> resolves to the same CommandDef instance as terok-executor sandbox vault <verb>, so wraps applied at one entry point apply at the other.

CommandTree.wire / CommandTree.dispatch do all the argparse plumbing.

__version__ = _meta_version('terok-executor') module-attribute

main(argv=None)

Run the terok-executor CLI.

Top-level options must precede the subcommand (terok-executor --config /path run claude .) — standard argparse subparser convention, matching the placement used by docker and kubectl.

argv (default sys.argv[1:]) is threaded into CommandTree.wire so only the invoked verb's module is imported: terok-executor run … pulls the run stack, not the whole terok_sandbox command tree.

Source code in src/terok_executor/cli.py 
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def main(argv: list[str] | None = None) -> None:
    """Run the terok-executor CLI.

    Top-level options must precede the subcommand
    (``terok-executor --config /path run claude .``) — standard argparse
    subparser convention, matching the placement used by ``docker`` and
    ``kubectl``.

    *argv* (default ``sys.argv[1:]``) is threaded into
    [`CommandTree.wire`][terok_util.cli_types.CommandTree.wire] so only
    the invoked verb's module is imported: ``terok-executor run …``
    pulls the run stack, not the whole ``terok_sandbox`` command tree.
    """
    raw_argv = list(sys.argv[1:] if argv is None else argv)
    os.environ.setdefault(_SETUP_INVOCATION_ENV, _SETUP_INVOCATION)
    parser = argparse.ArgumentParser(
        prog="terok-executor",
        description="Single-agent task runner for hardened Podman containers",
    )
    parser.add_argument("--version", action="version", version=f"terok-executor {__version__}")
    parser.add_argument(
        "--config",
        metavar="PATH",
        help=(
            "Override the config.yml path (sets TEROK_CONFIG_FILE for this invocation). "
            "Bypasses the layered system/user lookup."
        ),
    )
    parser.add_argument(
        "--raw",
        action="store_true",
        help=(
            "Ignore any config.yml — use sandbox/executor dataclass defaults only. "
            "Equivalent to '--config /dev/null'."
        ),
    )
    COMMANDS.wire(parser, argv=raw_argv)

    args = parser.parse_args(raw_argv)

    # Honour --config / --raw before dispatch so the very first
    # ``SandboxConfig()`` constructed by any handler sees the override.
    # SandboxConfig reads via ``terok_sandbox.paths._config_file_paths``,
    # which consults ``TEROK_CONFIG_FILE`` first.
    if args.raw:
        os.environ["TEROK_CONFIG_FILE"] = os.devnull
    elif args.config is not None:
        os.environ["TEROK_CONFIG_FILE"] = args.config

    if hasattr(args, "_cmd"):
        # Populate the agent registry once before any handler runs — the
        # package defers this out of import so ``--version`` / ``--help``
        # (which exit above) never pay the roster YAML load.
        _ensure_bootstrapped()
        from terok_executor.integrations.sandbox import NoPassphraseError

        try:
            CommandTree.dispatch(args)
        except NoPassphraseError as exc:
            # sandbox#278 stripped CLI-hint text from the library raise
            # sites so they stay diagnostic-only.  Standalone runs have no
            # orchestrator to add the remediation, so this front-end is
            # the operator-facing surface (mirrors terok's own wrapper).
            print(
                f"error: {exc}\n"
                "hint:  run `terok-executor vault unlock` to provision the"
                " vault passphrase for this session.",
                file=sys.stderr,
            )
            raise SystemExit(2) from exc
    elif hasattr(args, "_group_help"):
        args._group_help.print_help()
    else:
        parser.print_help()
        raise SystemExit(1)