goagent — Minimal, safe, non‐interactive agent CLI

Table of contents

At a glance

Features

Installation

Requirements

Install options

go install github.com/hyperifyio/goagent/cmd/agentcli@latest

git clone https://github.com/hyperifyio/goagent
cd goagent
make bootstrap tidy build build-tools

./bin/agentcli --version

# ripgrep
# - Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y ripgrep
# - macOS (Homebrew)
brew install ripgrep
# - Windows (Chocolatey)
choco install ripgrep -y
# golangci-lint (pinned; installs into ./bin via Makefile)
make install-golangci
./bin/golangci-lint version
# jq (used by examples and runbooks)
# - Ubuntu/Debian
sudo apt-get install -y jq
# - macOS (Homebrew)
brew install jq
# - Windows (Chocolatey)
choco install jq -y
# make (Windows, for running Makefile targets used in docs)
# - Windows (Chocolatey)
choco install make -y

Configuration

Inheritance and precedence

Quick start

export OAI_BASE_URL=http://localhost:1234/v1
export OAI_MODEL=oss-gpt-20b
make build build-tools # skip if installed via go install / release binary

{
 "tools": [
 {
 "name": "get_time",
 "description": "Return current time for an IANA timezone (default UTC). Accepts 'timezone' (canonical) and alias 'tz'.",
 "schema": {
 "type": "object",
 "properties": {
 "timezone": {"type": "string", "description": "e.g. Europe/Helsinki"},
 "tz": {"type": "string", "description": "Alias for timezone (deprecated)"}
 },
 "required": ["timezone"],
 "additionalProperties": false
 },
 "command": ["./tools/bin/get_time"],
 "timeoutSec": 5
 }
 ]
}

{
 "tools": [
 {
 "name": "get_time",
 "schema": {"type":"object","properties":{"timezone":{"type":"string"}},"required":["timezone"],"additionalProperties":false},
 "command": ["./tools/bin/get_time.exe"],
 "timeoutSec": 5
 }
 ]
}

./bin/agentcli \
 -prompt "What's the local time in Helsinki? If tools are available, call get_time." \
 -tools ./tools.json \
 -debug

Usage

Common flags

-prompt string User prompt (required)
-tools string Path to tools.json (optional)
-system string System prompt (default: helpful and precise)
-base-url string OpenAI‐compatible base URL (env OAI_BASE_URL; scripts accept LLM_BASE_URL fallback)
-api-key string API key if required (env OAI_API_KEY; falls back to OPENAI_API_KEY)
-model string Model ID (env OAI_MODEL; scripts accept LLM_MODEL fallback)
-max-steps int Maximum reasoning/tool steps (default 8)
 A hard ceiling of 15 is enforced; exceeding the cap
 terminates with: "needs human review".
-http-timeout duration HTTP timeout for chat completions (env OAI_HTTP_TIMEOUT; default falls back to -timeout)
-prep-http-timeout duration HTTP timeout for pre-stage (env OAI_PREP_HTTP_TIMEOUT; default falls back to -http-timeout)
-prep-model string Pre-stage model ID (env OAI_PREP_MODEL; inherits -model if unset)
-prep-base-url string Pre-stage base URL (env OAI_PREP_BASE_URL; inherits -base-url if unset)
-prep-api-key string Pre-stage API key (env OAI_PREP_API_KEY; falls back to OAI_API_KEY/OPENAI_API_KEY; inherits -api-key if unset)
-prep-http-retries int Pre-stage HTTP retries (env OAI_PREP_HTTP_RETRIES; inherits -http-retries if unset)
-prep-http-retry-backoff duration Pre-stage HTTP retry backoff (env OAI_PREP_HTTP_RETRY_BACKOFF; inherits -http-retry-backoff if unset)
-prep-dry-run Run pre-stage only, print refined Harmony messages to stdout, and exit 0
-print-messages Pretty-print the final merged message array to stderr before the main call
-http-retries int Number of retries for transient HTTP failures (timeouts, 429, 5xx). Uses jittered exponential backoff. (default 2)
-http-retry-backoff duration Base backoff between HTTP retry attempts (exponential with jitter). (default 300ms)
-tool-timeout duration Per-tool timeout (default falls back to -timeout)
-timeout duration [DEPRECATED] Global timeout; prefer -http-timeout and -tool-timeout
-temp float Sampling temperature (default 1.0)
-top-p float Nucleus sampling probability mass (conflicts with -temp; omits temperature when set)
-prep-top-p float Nucleus sampling probability mass for pre-stage (conflicts with -temp; omits temperature when set)
-prep-profile string Pre-stage prompt profile (deterministic|general|creative|reasoning); sets temperature when supported (conflicts with -prep-top-p)
-prep-enabled Enable pre-stage (default true). When false, skip pre-stage and proceed directly to main call.
-debug Dump request/response JSON to stderr
-verbose Also print non-final assistant channels (critic/confidence) to stderr
-channel-route name=stdout|stderr|omit
 Override default channel routing (final→stdout, critic/confidence→stderr); repeatable
-quiet Suppress non-final output; print only final text to stdout
-capabilities Print enabled tools and exit
-print-config Print resolved config and exit
-dry-run Print intended state actions (restore/refine/save) and exit without writing state
--version | -version Print version and exit

Image generation flags

Why you usually don’t need to change knobs

Capabilities

./bin/agentcli -tools ./tools.json -capabilities

Examples

Zero-config with GPT-5

./bin/agentcli -prompt "Say ok" -model gpt-5 -base-url "$OAI_BASE_URL" -api-key "$OAI_API_KEY" -max-steps 1 -debug
# stderr will include a request dump containing "\"temperature\": 1"

Tool calls transcript

[
 {"role":"user","content":"What's the local time in Helsinki?"},
 {
 "role":"assistant",
 "content":null,
 "tool_calls":[
 {
 "id":"call_get_time_1",
 "type":"function",
 "function":{
 "name":"get_time",
 "arguments":"{\"timezone\":\"Europe/Helsinki\"}"
 }
 }
 ]
 },
 {
 "role":"tool",
 "tool_call_id":"call_get_time_1",
 "name":"get_time",
 "content":"{\"timezone\":\"Europe/Helsinki\",\"iso\":\"2025年08月17日T12:34:56Z\",\"unix\":1755424496}"
 },
 {"role":"assistant","content":"It's 15:34 in Helsinki."}
]

Worked example: tool calls and transcript

go test ./examples -run TestWorkedExample_ToolCalls_TemperatureOne_Sequencing -v

Split backends for chat and image

export OAI_BASE_URL=https://api.example-chat.local/v1
export OAI_API_KEY=chat-key
./bin/agentcli \
 -prompt "Create a simple logo" \
 -tools ./tools.json \
 -image-base-url https://api.openai.com/v1 \
 -image-api-key "$OPENAI_API_KEY" \
 -image-model gpt-image-1 \
 -image-size 1024x1024

View refined messages (pre-stage and final)

# Pre-stage only: print refined Harmony messages and exit
./bin/agentcli -prompt "Say ok" -prep-dry-run | jq .
# Before the main call: pretty-print merged messages to stderr, then proceed
./bin/agentcli -prompt "Say ok" -print-messages 2> >(jq .)

Exec tool

make build-tools
echo '{"cmd":"/bin/echo","args":["hello"]}' | ./tools/bin/exec
# => {"exitCode":0,"stdout":"hello\n","stderr":"","durationMs":<n>}

echo '{"cmd":"/bin/sleep","args":["2"],"timeoutSec":1}' | ./tools/bin/exec
# => non-zero exit, stderr contains "timeout"

Filesystem tools

fs_read_file

make build-tools
printf 'hello world' > tmp_readme_demo.txt
echo '{"path":"tmp_readme_demo.txt"}' | ./tools/bin/fs_read_file | jq .
rm -f tmp_readme_demo.txt

fs_append_file

make build-tools
echo -n 'hello ' | base64 > b64a.txt
echo -n 'world' | base64 > b64b.txt
echo '{"path":"tmp_append_demo.txt","contentBase64":"'"$(cat b64a.txt)"'"}' | ./tools/bin/fs_append_file | jq .
echo '{"path":"tmp_append_demo.txt","contentBase64":"'"$(cat b64b.txt)"'"}' | ./tools/bin/fs_append_file | jq .
cat tmp_append_demo.txt; rm -f tmp_append_demo.txt b64a.txt b64b.txt

fs_write_file

make build-tools
echo -n 'hello world' | base64 > b64.txt
echo '{"path":"tmp_write_demo.txt","contentBase64":"'"$(cat b64.txt)"'"}' | ./tools/bin/fs_write_file | jq .
cat tmp_write_demo.txt; rm -f tmp_write_demo.txt b64.txt

fs_mkdirp

make build-tools
echo '{"path":"tmp_mkdirp_demo/a/b/c","modeOctal":"0755"}' | ./tools/bin/fs_mkdirp | jq .
ls -ld tmp_mkdirp_demo/a/b/c
echo '{"path":"tmp_mkdirp_demo/a/b/c","modeOctal":"0755"}' | ./tools/bin/fs_mkdirp | jq .
rm -rf tmp_mkdirp_demo

fs_rm

make build-tools
printf 'temp' > tmp_rm_demo.txt
echo '{"path":"tmp_rm_demo.txt"}' | ./tools/bin/fs_rm | jq .
mkdir -p tmp_rm_dir/a/b && touch tmp_rm_dir/a/b/file.txt
echo '{"path":"tmp_rm_dir","recursive":true}' | ./tools/bin/fs_rm | jq .
rm -rf tmp_rm_dir

fs_move

make build-tools
printf 'payload' > tmp_move_src.txt
echo '{"from":"tmp_move_src.txt","to":"tmp_move_dst.txt"}' | ./tools/bin/fs_move | jq .
printf 'old' > tmp_move_dst.txt; printf 'new' > tmp_move_src.txt
echo '{"from":"tmp_move_src.txt","to":"tmp_move_dst.txt","overwrite":true}' | ./tools/bin/fs_move | jq .
rm -f tmp_move_src.txt tmp_move_dst.txt

fs_listdir

make build-tools
mkdir -p tmp_listdir_demo/a b && touch tmp_listdir_demo/.hidden tmp_listdir_demo/a/afile tmp_listdir_demo/bfile
echo '{"path":"tmp_listdir_demo"}' | ./tools/bin/fs_listdir | jq '.entries | map(.path)'
jq -n '{path:"tmp_listdir_demo",recursive:true,globs:["**/*"],includeHidden:false}' | ./tools/bin/fs_listdir | jq '.entries | map(select(.type=="file") | .path)'
rm -rf tmp_listdir_demo

fs_apply_patch

make build-tools
cat > /tmp/demo.diff <<'EOF'
--- /dev/null
+++ b/tmp_patch_demo.txt
@@ -0,0 +1,2 @@
+hello
+world
EOF
jq -n --arg d "$(cat /tmp/demo.diff)" '{unifiedDiff:$d}' | ./tools/bin/fs_apply_patch | jq .
printf 'hello
world
' | diff -u - tmp_patch_demo.txt && echo OK

fs_edit_range

make build-tools
printf 'abcdef' > tmp_edit_demo.txt
echo -n 'XY' | base64 > b64.txt
jq -n --arg b "$(cat b64.txt)" '{path:"tmp_edit_demo.txt",startByte:2,endByte:4,replacementBase64:$b}' | ./tools/bin/fs_edit_range | jq .
cat tmp_edit_demo.txt # => abXYef
rm -f tmp_edit_demo.txt b64.txt

fs_stat

make build-tools
printf 'hello world' > tmp_stat_demo.txt
echo '{"path":"tmp_stat_demo.txt","hash":"sha256"}' | ./tools/bin/fs_stat | jq .
rm -f tmp_stat_demo.txt

Image generation tool (img_create)

make build-tools

{
 "tools": [
 {
 "name": "img_create",
 "description": "Generate image(s) with OpenAI Images API and save to repo or return base64",
 "schema": {
 "type": "object",
 "required": ["prompt"],
 "properties": {
 "prompt": {"type": "string"},
 "n": {"type": "integer", "minimum": 1, "maximum": 4, "default": 1},
 "size": {"type": "string", "pattern": "^\\d{3,4}x\\d{3,4}$", "default": "1024x1024"},
 "model": {"type": "string", "default": "gpt-image-1"},
 "return_b64": {"type": "boolean", "default": false},
 "save": {
 "type": "object",
 "required": ["dir"],
 "properties": {
 "dir": {"type": "string"},
 "basename": {"type": "string", "default": "img"},
 "ext": {"type": "string", "enum": ["png"], "default": "png"}
 },
 "additionalProperties": false
 }
 },
 "additionalProperties": false
 },
 "command": ["./tools/bin/img_create"],
 "timeoutSec": 120,
 "envPassthrough": ["OAI_API_KEY", "OAI_BASE_URL", "OAI_IMAGE_BASE_URL", "OAI_HTTP_TIMEOUT"]
 }
 ]
}

export OAI_BASE_URL=${OAI_BASE_URL:-https://api.openai.com/v1}
export OAI_API_KEY=your-key
./bin/agentcli \
 -tools ./tools.json \
 -prompt "Generate a tiny illustrative image using img_create and save it under assets/ with basename banner" \
 -debug
# Expect: one or more PNGs under assets/ (e.g., assets/banner_001.png) and a concise final message on stdout

fs_search

make build-tools
mkdir -p tmp_search_demo && printf 'alpha\nbeta\ngamma\n' > tmp_search_demo/sample.txt
jq -n '{query:"^ga",globs:["**/*.txt"],regex:true}' | ./tools/bin/fs_search | jq '.matches'
rm -rf tmp_search_demo

Security

Unrestricted tools warning

State persistence (-state-dir)

# First run saves a snapshot
./bin/agentcli -prompt "Say ok" -tools ./tools.json -state-dir "$PWD/.agent-state"
# Restore and skip pre-stage
./bin/agentcli -prompt "Say ok" -tools ./tools.json -state-dir "$PWD/.agent-state"
# Refine existing state with inline text
./bin/agentcli -prompt "Say ok" -state-dir "$PWD/.agent-state" -state-refine -state-refine-text "Tighten tone"
# Use a custom scope to keep contexts separate
./bin/agentcli -prompt "Say ok" -state-dir "$PWD/.agent-state" -state-scope docs-demo

Troubleshooting

Documentation

Diagrams

Tests

go test ./...

make lint
make fmt # apply gofmt -s -w to the repo

# Only removes ./logs when ./logs/STATE trimmed equals DOWN
make clean-logs
# End-to-end verification of the guard logic (creates temp dirs)
make test-clean-logs

Contributing

Go toolchain mismatch: system X.Y != go.mod X.Y

Tooling

Support

Roadmap

Project status

License and credits

Changelog

More examples