How-to › Use AI to do the integration

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.

Audience
Agent builder
Level
advanced
Topic
Build an agent that calls APIs
Languages
Go and TypeScript
Verified

Read first: Design a CLI a coding agent can drive

Your API has forty-one operations, so every request your agent sends carries forty-one tool definitions before it has done any work. Replace them with one shell tool and the agent can write files, call other hosts, and read a progress meter mixed into the JSON it is trying to parse.

What you get

You will end up with one shell tool that runs only the programs you allow, four routes through it to the same API, and a task check that reads the API’s state. This is for you if your agent calls an API and you want to know what a CLI buys and costs.

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 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

ApproachWhen it fitsWhat it costs youWhen to pick something else
cobra CLI on an ogen clientA Go team that wants JSON output and every operation it needsA CLI to write and keep, because ogen generates a client and no command lineYou would rather generate the CLI than own it
curl with jqAny HTTP API, with nothing to buildLong commands, and a curl allowlist strict enough to stop file writesThe agent repeats the same calls and you want short ones
Swagger Codegen 2.4 Bash clientA Swagger 2.0 document and a machine with Bash and curlParameter values reach eval, and curl options pass straight through to curlThe document is OpenAPI 3, or the arguments come from a model
Voxgig SDK catalog Go CLIA public API already in the catalog, read more than writtenThree words only, boru notation instead of JSON, and keys in changing orderThe 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.

node tools.mjs
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. 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.

  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:

    // 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:

node sandbox.mjs
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 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:

node agent.mjs curl-jq
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:

node report.mjs
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

node --test agent.test.mjs
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:

node progress.mjs
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 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.

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.

Footnotes

  1. The JSONPlaceholder 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. ↩︎ Back to text

  2. The Swagger Codegen 2.4.53 README 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. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.