# How to let an agent drive a CLI instead of tool schemas

> Give an agent one shell tool in a sandbox and a CLI over your API in place of one tool per operation, then check every task against what the API holds.

Source: https://voxgig.com/howto/let-an-agent-drive-a-generated-cli

- Audience: agent-builder
- Level: advanced
- Languages: go, typescript
- Verified: 2026-11-22
- Published: 2026-11-22

## Short answer

Give the agent one tool that starts an allowlisted CLI without a shell, with a fixed environment, a timeout, and stdout and stderr returned apart. Check each task against the API's state, not against what the CLI printed. One shell tool and a help text cost a small fraction of the tokens of one definition per operation. The CLI's own commands then decide which tasks the agent can finish.

---
## You will need

Node 22 or later with curl and jq, a CLI over your API, and an agent loop that can run commands.
The API here is a stand-in for [JSONPlaceholder](https://jsonplaceholder.typicode.com/#guide) on
127.0.0.1. It answers with the real service's routes, status codes, and record shapes, its records
hold invented values, and it keeps writes.[^1]

No model runs anywhere on this page. A scripted policy in `policies.mjs` issues the commands a
model would send, in order, and decides what to do with each result. The page therefore tests the
CLIs and the loop, not what a model would choose.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [cobra CLI on an `ogen` client](https://ogen.dev/docs/config/) | A Go team that wants JSON output and every operation it needs | A CLI to write and keep, because `ogen` generates a client and no command line | You would rather generate the CLI than own it |
| [curl with jq](https://curl.se/docs/manpage.html) | Any HTTP API, with nothing to build | Long commands, and a curl allowlist strict enough to stop file writes | The agent repeats the same calls and you want short ones |
| [Swagger Codegen 2.4 Bash client](https://github.com/swagger-api/swagger-codegen/tree/v2.4.53) | A Swagger 2.0 document and a machine with Bash and curl | Parameter values reach `eval`, and curl options pass straight through to curl | The document is OpenAPI 3, or the arguments come from a model |
| [Voxgig SDK catalog Go CLI](https://github.com/voxgig-sdk/jsonplaceholder-sdk/blob/main/go-cli/README.md) | A public API already in the catalog, read more than written | Three words only, `boru` notation instead of JSON, and keys in changing order | The agent must create or delete records |

Voxgig maintains the SDK catalog and its CLIs. The catalog CLI is one of four rows here, not the
recommendation.

curl and jq reach every operation and need the strictest argument checks, because curl can do
almost anything. The `ogen` route gives clean JSON and exit codes, but someone writes and maintains
it. The two generated CLIs cost nothing to write, and each one limits or endangers the agent in
its own way.

## Count what each route puts in every request

Each tool definition travels with every request the agent sends. `tools.mjs` turns each operation in the
catalog's own JSONPlaceholder document into a tool definition, and measures it beside the one shell
tool the catalog route sent.

```bash
node tools.mjs
```

```text output
per-operation tools from the catalog's JSONPlaceholder document
  41 tools, 15030 bytes, 3311 tokens in every request
one shell tool for the catalog CLI
  1 tool, 585 bytes, 142 tokens in every request
  plus --help, read once: 478 bytes, 114 tokens
  what --help offers: list / load / update <query?> <entity>
```

The tokens are counted with the `cl100k_base` encoding of
[js-tiktoken](https://github.com/dqbd/tiktoken). For a model with another tokenizer the counts are
an estimate, so read them as an order of magnitude. The last line is the cost of the saving: the
catalog CLI's help offers three words, where the document has 41 operations.

## Give the agent one tool that runs no shell

The tool takes a pipeline of argument arrays, at most three stages, and starts each program itself.
Nothing reaches a shell, so there is no globbing, no `$(...)` and no redirection to refuse.

```js title="shell.mjs"
  return async function run(input) {
    const bad = checkInput(input)
    if (bad) return { refused: bad }
    for (const [name, ...args] of input.pipeline) {
      if (!Object.hasOwn(programs, name)) return { refused: `${name} is not on the allowlist` }
      const why = programs[name].check(args)
      if (why) return { refused: `${name}: ${why}` }
    }
    const cwd = mkdtempSync(join(tmpdir(), 'agent-run-'))
    try {
      return await execute(input.pipeline, { programs, env, cwd, timeoutMs, maxBytes })
    } finally {
      rmSync(cwd, { recursive: true, force: true })
    }
```

Each program has its own argument check in `programs.mjs`. curl accepts a few options and one URL
on the API's origin, and jq accepts one filter and no filenames. The environment is a fixed
object, so nothing the agent's host process holds leaks into a child:

```js title="agent.mjs"
    // The whole environment the programs see. Nothing is inherited from this process.
    const env = { PATH: SYSTEM_DIRS.join(':'), HOME: '/nonexistent', LANG: 'C', JSONPLACEHOLDER_BASE: base }
```

`sandbox.mjs` sends nine commands a model could send and prints what the tool did with each:

```bash
node sandbox.mjs
```

```text output
sh -c 'curl -s {base}/posts/1'
  refused: sh is not on the allowlist
curl -s https://example.com/posts/1
  refused: curl: "https://example.com/posts/1" does not start with the API's origin
curl -s '{base}\@example.com/posts/1'
  refused: curl: "{base}\\@example.com/posts/1" holds a character curl reads differently
curl -s -o copy.json {base}/posts/1
  refused: curl: option -o is not allowed
curl -s -d @/etc/passwd {base}/posts
  refused: curl: reading request data from a file is not allowed
jp-bash --host https://example.com getPost id=1
  refused: jp-bash: operation --host is not allowed
jp-bash createPost 'title==x'$(touch pwned)''
  refused: jp-bash: parameter "title==x'$(touch pwned)'" is not allowed
curl -s {base}/posts/1 | jq . | jq . | jq .title
  refused: pipeline must hold one to three stages
jq -n -c 'env | keys'
  exit 0: ["HOME","JSONPLACEHOLDER_BASE","LANG","PATH"]
requests that reached the stand-in: 0
```

The tool runs on Node's [`child_process.spawn`](https://nodejs.org/api/child_process.html) with
`shell: false`. The allowlist is the security boundary, so test its neighbors. The sample's tests
feed each check a URL with a user part, another scheme, a second URL, curl's glob brackets, and an
unknown option. The backslash case matters because curl reads `{base}\@example.com` as a user part
and the host `example.com`, where Node's `URL` sees the API.

Each program starts in a process group of its own, so the timeout reaches its children. At
the deadline the tool sends SIGTERM to the group, and SIGKILL to whatever is left a quarter second
later. It then returns exit 124 without waiting on a stream a child still holds open. The Bash
client runs curl through `eval`, so a stalled request would otherwise keep the tool waiting for as
long as curl waited.

## Drive the four tasks and check the API

Four tasks run on every route: read a title, count open to-do items, rename a post and keep its body,
and create a post. Each check reads the stand-in's records afterwards. Every pass count on this page
is a scripted policy against the stand-in, not a measure of what a model would do. curl and jq run
live:

```bash
node agent.mjs curl-jq
```

```text output
route: curl + jq

load: What is the title of post 3?
  run    curl -s -f {base}/posts/3 | jq -r .title
  exit   0
  stdout "post 3 title"
  answer "post 3 title"  check: pass

count: How many open todos does user 2 have?
  run    curl -s -f '{base}/todos?userId=2&completed=false' | jq length
  exit   0
  stdout "13"
  answer 13  check: pass

rename: Rename post 1 to "Shelved" and keep its body.
  run    curl -s -f -X PATCH -H 'content-type: application/json' -d '{"title":"Shelved"}' {base}/posts/1 | jq -c '{id, title}'
  exit   0
  stdout "{\"id\":1,\"title\":\"Shelved\"}"
  answer {"id":1,"title":"Shelved"}  check: pass

create: Create a post for user 2 titled "Draft".
  run    curl -s -f -X POST -H 'content-type: application/json' -d '{"userId":2,"title":"Draft","body":""}' {base}/posts | jq -c '{id, title}'
  exit   0
  stdout "{\"id\":101,\"title\":\"Draft\"}"
  answer {"id":101,"title":"Draft"}  check: pass

tasks passed: 4 of 4
```

The other three routes need binaries the gate cannot build offline, so `record.sh` built them,
drove the same tasks through the same tool once, and committed the runs. `report.mjs` reads them:

```bash
node report.mjs
```

```text output
route                                     tasks   tool calls  failed
cobra CLI on an ogen client               4 of 4  5           none
curl + jq                                 4 of 4  4           none
Swagger Codegen 2.4 Bash client           4 of 4  5           none
Voxgig SDK catalog Go CLI                 2 of 4  5           rename, create
Voxgig SDK catalog Go CLI, whole record   3 of 4  6           create

Voxgig SDK catalog Go CLI
  update sent: PUT /posts/1 { "id": 1, "title": "Shelved" }
  10 loads of one post: 3 distinct outputs, same keys every time: yes
  --json: exit 1, error: [boru/undefined_word]: undefined word: --json
  no arguments, stdin closed: exit 0, stdout "jsonplaceholder>"
Swagger Codegen 2.4 Bash client, called without the tool
  a quote in a value: exit 0, the command inside it ran: yes
  -o before the operation: exit 0, wrote copy.json: yes
  a missing post: exit 0, stdout {}
cobra CLI on an ogen client
  a missing post: exit 1, stderr {"error":"decode response: unexpected status code: 404","status":404}
  --verbose: stderr "fetching post 3", stdout still parses: yes
```

The catalog CLI printed `{id:1 title:'Shelved'}` for the rename, which reads as success. Its
`update` is the document's PUT, carrying only the fields it was given. The stand-in stores a PUT as
the whole record, as JSONPlaceholder's answer to such a PUT shows, so the body was gone. The loss
happened on the stand-in, because the real service stores no write, and only the check against
the records caught it. The whole-record run loads the
post first and sends every field back; it passes the rename and still cannot create, because the
CLI has no `create` word.

## Check it worked

```bash
node --test agent.test.mjs
```

```text output
1..14
# tests 14
# suites 0
# pass 14
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 2209.048911
```

The first test runs the curl route live and compares it with its recording, call for call. Others
hold each recorded route to its task results, and the stand-in to the routes and status codes the
real service answered with. The timeout tests check that no process a program started outlives the
tool.

## When it goes wrong

The JSON does not parse. curl writes its progress meter to stderr, and a tool that collects both
streams into one string puts the meter in front of the body:

```bash
node progress.mjs
```

```text output
command                     exit  stdout alone parses  both streams parse  first bytes of both
curl {base}/posts/1         0     yes                  no                  "  % Total    % Receive"
curl -s {base}/posts/1      0     yes                  yes                 "{\n  \"userId\": 1,\n  \"id"
```

Return stdout and stderr apart, and parse stdout only. The generated Bash client calls curl
without `-s`, so it shows the meter on every call, and only the split saved its route.

The parse works once and fails the next time. The catalog CLI prints `boru` notation, which
`JSON.parse` refuses, and ten loads of one post came back in more than one key order. Read fields
by name, as the catalog policy does with a pattern, and never compare its output as text.

A failed call looks like success. The Bash client exits 0 on a 404 and prints `{}`, so the exit
code tells the agent nothing. Check the body, or prefer a CLI that exits 1, as the `ogen` route does.

## Drive a Swagger Codegen client and a Go CLI you write

`ogen` writes Go clients and servers. Its
[configuration page](https://ogen.dev/docs/config/) lists clients, servers, webhooks and
telemetry as features. The full list in its repository's `gen/features.go` at v1.24.0 has no
command line either, so a team on `ogen` writes the CLI itself. The
sample's `ogen-cli/main.go` wraps the generated client in cobra commands, with
JSON on stdout, a JSON error on stderr, and exit 2 for bad usage. The scripted policy completed all four tasks through it. It
is the better choice when you need writes and stable output, and can afford to own the code.

Swagger Codegen's 2.x line ships a `bash` client generator, and its 3.0.85 `langs` list has none.
The 2.4.53 client read the page's Swagger 2.0 document, and the tool pins its `--host` for it. Two
things make its argument check necessary. A value holding a quote ran the command inside it, because
the script builds curl's command line and passes it to `eval`. A curl option placed before the
operation reached curl, and `-o` wrote a file. Do not hand this client to an agent without the argument check `programs.mjs` puts in front of it,
which the tests hold to each of those inputs. With the check in place, the scripted policy completed
all four tasks through it. It is the better choice for a Swagger 2.0 API whose callers have only
Bash and curl.[^2]

## When not to do this

Do not hand an agent a shell with your credentials in its environment. Build the environment
yourself, as `agent.mjs` does, and give each program an argument check that refuses by default.

Do not trust a CLI's output as proof that a task finished. The catalog CLI's rename printed a
plausible record while the post lost its body.

Skip the Voxgig SDK catalog CLI when the agent must create or delete: it offers `list`, `load` and
`update` only. Pick the cobra CLI on an `ogen` client when you need every operation as JSON and can
own the code. Keep per-operation tools when you have a handful of operations, because a few typed
schemas let the model's own tool-calling check the arguments.

## Related how-tos

- [Design a CLI a coding agent can drive](/howto/design-a-cli-a-coding-agent-can-drive)

- [Choose Restish, a generated CLI, or a hand-written one](/howto/choose-restish-generated-or-hand-written-cli)

- [Choose between calling an SDK directly and using MCP](/howto/direct-sdk-calls-versus-mcp-in-an-agent)

- [Run a coding agent in a sandbox with a mock API](/howto/coding-agent-sandbox-with-a-mock-api)

- [Build an oclif CLI with one topic per API resource](/howto/build-an-oclif-cli-with-topics-per-resource)

## Last verified

Verified 2026-11-22 against Node 22.23.5, curl 8.5.0, jq 1.7 and js-tiktoken 1.0.21. The curl
route, the sandbox, and the progress commands run live. `record.sh` built the catalog CLI at
`a21ce5a97d8e` with Go 1.24.7, generated the `ogen` v1.24.0 client and its cobra CLI with Go 1.25.0,
and generated the Bash client with Swagger Codegen 2.4.53. It drove each once against the same
stand-in, and `report.mjs` reads what it committed. No task run or probe sent a request beyond the loopback interface.

[^1]: The [JSONPlaceholder guide](https://jsonplaceholder.typicode.com/#guide) says of a created
post that the resource is not really created on the server, "but the response is faked as if" in
its place. A check that reads the records back has nothing to read on the real service, which is why the
stand-in keeps what it is sent.

[^2]: The Swagger Codegen 2.4.53
[README](https://github.com/swagger-api/swagger-codegen/tree/v2.4.53) lists its API clients
alphabetically, so Bash sits between Apex and C#. The client it writes calls curl, `sed`, and
`column`, checks for all three before it starts, and names the missing package when `column` is
absent: bsdmainutils.