CLI

The goro command line client wraps the same HTTP API your agent uses. It is useful for three things: setting up a key once, exploring the catalog by hand before you wire anything up, and scripting calls where a full agent would be overkill. Human-readable by default, raw JSON on demand, and an exit code that says what happened so a shell script can branch on it.

Install

npm install -g @goroo/cli

That installs a goro command. The package is scoped because the bare goro name on npm belongs to an unrelated project.

Prefer not to install globally? npx @goroo/cli discover -q "..." works the same way.

First run

goro setup

It prompts for an API key, verifies it against the gateway, and stores it in ~/.goro/config.json with permissions 0600. The key is never echoed while you paste it and is never printed back afterwards.

Key verified and stored.
  name       default  (active)
  key        goro_live_mz...WNE0
  workspace  b818a36d-bfb6-4111-a0aa-ce14cfbbb34e
  gateway    https://api.usegoro.ai
  config     /Users/you/.goro/config.json (mode 0600)
Next: goro balance

The commands

Command	What it does
`goro setup`	Store and verify your first API key
`goro keys add`	Store an additional key
`goro keys list`	Show stored keys, prefix and last 4 only
`goro keys use <name>`	Switch the active key
`goro discover -q "<query>"`	Find tools that can answer a question
`goro inspect -s <slug>`	Show a tool’s input, price and sample input
`goro run -s <slug> -i '<json>'`	Run a tool
`goro runs get -r <runId>`	Fetch one run
`goro runs list`	List recent runs
`goro balance`	Show the wallet balance

Global options

Option	Meaning
`-j`, `--json`	Emit the raw JSON response instead of a rendered view
`-o <file>`	Write the JSON response to a file
`--api <url>`	Point at a different gateway, for example a local one
`-h`, `--help`	Help for the CLI or for one command
`-V`, `--version`	Print the CLI version

-j and -o are independent. -o always writes the same JSON -j prints, so you can keep a readable terminal and still capture the machine-readable result:

goro run -s web.search -i '{"queries":"cold brew ratio"}' -o results.json

Exit codes

Every command exits with one of five codes. Scripts branch on these rather than parsing output.

Code	Meaning	What to do
`0`	Success	Continue
`1`	Usage error	Fix the command, the slug or the input JSON
`2`	Auth failure	The key is missing, wrong or revoked
`3`	Insufficient funds	Top up, or raise the budget cap
`4`	Upstream failure	The provider or gateway failed, retry later

goro run -s web.search -i "$INPUT" -o out.json
case $? in
  0) echo "got results" ;;
  3) echo "out of money, stopping" ; exit 1 ;;
  4) echo "upstream flaked, retrying in 60s" ; sleep 60 ;;
esac

A run that comes back FAILED or TIMED_OUT also exits 4, even though the HTTP call itself succeeded. The run is what you asked about, so the run is what the exit code reports on.

How prices read

The CLI shows two different kinds of number and never mixes them up.

A rate is exact

A rate is what one unit costs you: a row, a page, a second of audio. It prints flat, with no hedging: $0.0069 per profile. A flat-priced tool prints the same way, and there the rate is the whole price: $0.18 per call.

A ceiling is a maximum

Before a call runs, the price attached to a tool is a ceiling for your request, not a prediction. It always prints with the words “up to”, for example up to $6.00 per call. You are never charged above it, and the final charge is usually well below it.

A charge is what happened

After a call completes, the CLI shows what it actually cost and what that works out to per result: charged $0.0105 (1 result, $0.0105 each).

See Pricing for how the hold and the final charge are computed.

Environment

Variable	Effect
`GORO_API_KEY`	Use this key, overriding anything stored
`GORO_API_URL`	Gateway base URL, below `--api` and above stored config
`GORO_CONFIG_HOME`	Config directory, default `~/.goro`

GORO_API_KEY is the one to reach for in CI: nothing is written to disk, and no setup step is needed.

GORO_API_KEY=$GORO_KEY goro run -s web.search -i '{"queries":"ai agents"}' -j

Every command, with examples

Piping to jq, scripting retries, and running a batch of inputs.

Guide

CLI reference

API reference

Tools

Install

First run

The commands

Global options

Exit codes

How prices read

Environment

Every command, with examples

​Install

​First run

​The commands

​Global options

​Exit codes

​How prices read

​Environment

Every command, with examples

Install

First run

The commands

Global options

Exit codes

How prices read

Environment