cli-to-tools

Translate shell command lines into ordered, structured tool calls, so that an agent working through a single bash(command=...) tool can be constrained by a tool-call harness such as AgentLTL.

📖 Documentation: agentltl.github.io/shell, including every supported command with its tools and arguments.

from cli_to_tools import Translator

for call in Translator().translate('git add . && git commit -am "fix" | tee log; echo $(cat VERSION)'):
    print(call.name, call.args)
# git_add     {"paths": ["."], ...}
# git_commit  {"message": ["fix"], "all": True, ...}
# tee         {"paths": ["log"], ...}
# cat         {"paths": ["VERSION"], ...}     <- runs before the echo that consumes it
# echo        {"words": ["$(cat VERSION)"], ...}

The library only translates. Executing the command line stays with the caller.

Install

Paste this into your coding agent (Claude Code, Codex, Copilot CLI, Mistral Vibe...):

Install cli-to-tools from https://github.com/AgentLTL/cli-to-tools in a virtual environment (pip install "git+https://github.com/AgentLTL/cli-to-tools.git"), then use cli_to_tools.Translator to translate a shell command line of mine into tool calls and show me the result.

Or install manually:

pip install -e ".[dev]"
pip install -e /path/to/AgentLTL      # only for cli_to_tools.agentltl
pytest

How it works

1. Shell layer – the command line is parsed with tree-sitter-bash and the parse tree is walked in execution order: ;, &&, || and | left to right; commands inside $(...), backticks and <(...) before the command that consumes them; subshells and { ...; } groups flattened.
2. Specs – each simple command is matched against a command spec, which gives it a tool name (git_commit, docker_compose_up) and flat named arguments.
3. Fallback – a command without a spec becomes tool_name=<executable>, arguments={"argv": [...]}.

Each ToolCall has name, args, id and meta. to_dict() returns AgentLTL's trace format, {"tool_name", "arguments", "id", "cli": meta}, where meta holds:

Conditional chains are over-approximated: every command that could run is emitted.

Control flow

The second and third rows are over-approximations. They are sound for constraints on names and order ("never call X", Before), but not for counts (CalledNTimes) or exact argument values, because the number of iterations and the run-time values are unknown. Translator(strict=True) rejects those constructs instead; literal for loops are exact and stay allowed.

Wrappers

Commands that run other commands are unwrapped, so they cannot hide a call: sudo, doas, env, time, timeout, nohup, setsid, nice, stdbuf, watch, exec, command, builtin, xargs, find -exec, python -m <module>, and bash -c '<script>' (the script is parsed recursively). The wrapper is emitted first, then the wrapped call.

Not unwrapped: commands that run a command string elsewhere or in another language (ssh host '<cmd>', docker exec ... <cmd>, python -c, make, npx, scripts such as bash script.sh). These appear as one call with the command visible in its arguments; forbid or restrict them in your constraints if that matters.

What commands do to files

Translator(shell_effects=True, paths=Paths(cwd, root)) adds what a guard needs on top of the arguments themselves:

Path arguments are made absolute, resolved from the directory the line has moved to: in cd sub && rm a, a is sub/a. A cd lasts until the end of its subshell, one in a pipeline changes nothing, and after cd $D relative paths are unknown. Which arguments hold paths: those named in PATH_NAMES (path, paths, file, destination, ...), plus any a spec marks path: true (and minus those it marks path: false). Tool schemas show them with "format": "path".

Fail closed

translate() raises TranslationError instead of guessing on: syntax errors, function definitions, background jobs (&), eval / source / ., a non-static command name ($CMD args, including a loop variable that cannot be resolved), a dynamic bash -c "$X", and a shell reading its script from stdin (curl ... | sh).

Specs

These packs are bundled and loaded by default:

They cover the commonly used subcommands and flags, not complete man pages:

• Unknown flags are kept in extra_args.
• An undeclared subcommand still gets a predictable name: git frob x becomes git_frob, with {"argv": [...]}.
• Global flags: options a CLI accepts anywhere are marked global: true, so kubectl delete pod x -n prod records namespace: prod. That applies to kubectl's -n and --context, gh's -R, and aws's --profile and --region.

from cli_to_tools import CommandSpec, SpecRegistry, Translator

registry = SpecRegistry()                      # all packs; SpecRegistry(packs=["shell", "git"]) to pick
registry.load_yaml("my_specs.yaml")            # add or override from YAML

deploy = registry.register(CommandSpec("deploy"))   # or in Python: plain argparse arguments
deploy.add_argument("-e", "--env", dest="environment")
deploy.add_argument("--force", action="store_true")
deploy.add_argument("services", nargs="*")

translator = Translator(registry)

# my_specs.yaml
deploy:
  tool: deploy                 # optional tool name override
  aliases: [dpl]
  posix: false                 # true: options stop at the first positional (docker run IMAGE CMD...)
  options:
    - {flags: [-e, --env], dest: environment}
    - {flags: [--force], type: bool}          # str (default) | bool | count | list | int
    - {flags: [--mode], choices: [fast, safe], help: "How to deploy."}   # optional, for tool schemas
    - {flags: [-n, --namespace], global: true}   # also accepted after a subcommand
    - {flags: [--manifest], path: true}          # holds a file path (see shell_effects)
  positionals:
    - {name: services, nargs: "*"}
  subcommands: {}              # nested specs, same schema -> tool "deploy_<name>"

kubectl:
  extend: true                 # add to the bundled kubectl spec instead of replacing it
  subcommands:
    rollout: {positionals: [{name: action}, {name: resource}]}

A later spec for the same command replaces the earlier one, unless it says extend: true: then its options are merged by flag and its subcommands one by one. registry.load_dict(specs, extend=True) extends by default.

Boolean flags are always present in the arguments (False when absent), so both CalledWith("rm", {"recursive": True}) and CalledWith("git_push", {"force": False}) work.

AgentLTL

ShellEnforcer is an agentltl.Enforcer (AgentLTL 0.2 or later). Calls to a shell tool are expanded into the structured calls of the command line and checked with Enforcer.check_chain; every other tool is checked unchanged.

from agentltl import Before, CalledWith, Constraint, Globally, Not
from cli_to_tools.agentltl import ShellEnforcer

enforcer = ShellEnforcer(
    [
        Constraint("commit_before_push", Before("git_commit", "git_push")),
        Constraint("no_force_push", Globally(Not(CalledWith("git_push", {"force": True})))),
    ],
    shell_tools={"bash": "command"},           # tool name -> argument holding the command line
)

decision = enforcer.check("bash", {"command": "git push && git commit -m x"})
decision.action, decision.index                # ("stop", 0): the first command, git push

CliConstraintEnforcer is the same with AgentLTL's original ConstraintEnforcer interface ("allow" or (kind, feedback), raising on a stop).

• All or nothing. The calls of a chain are checked in order, each against a trace that already contains the earlier calls of the same chain. If any call is blocked, the whole command line is rejected and nothing is recorded, so nothing should be executed.
• Untranslatable command lines are blocked with feedback telling the model how to rephrase, and listed in enforcer.untranslatable.
• record_completed stores one trace entry per structured call (with the cli metadata, so Predicates can read call.raw["cli"]). The tool result and exit status (status=) are attached to the last call.
• Native backend: with AgentLTL's cli extra, pass shell_tools={"bash": "command"} to AgentWithConstraints(backend="native"), MultiTurnAgent or NativeOpenAIAgent; the agent then uses this enforcer and emits the structured calls in metrics["tool_calls"]. On an AgentLTL without that option: agent._enforcer = CliConstraintEnforcer.from_enforcer(agent._enforcer).
• Post hoc: expand_tool_calls(metrics["tool_calls"]) rewrites a recorded trace before verify_trace.

See examples/02_agentltl_guard.py for a runnable walk-through.