CLI (agctl)

agctl runs Agent SDK for Go from your terminal — one-shot prompts or multi-turn chat, with built-in tools, optional MCP servers, and local, Temporal, or Restate execution. Configuration is YAML plus environment variables.

agctl is not the Go library. If you’re building an app in Go, install the SDK with go get github.com/agenticenv/agent-sdk-go. Install agctl separately using one of the methods below.

Install

GitHub Releases (recommended)

Pre-built binaries for Linux, macOS, and Windows (amd64 and arm64) are published on GitHub Releases.

Open the latest release.
Download the archive for your OS and architecture from Assets.
Extract agctl and place it on your PATH.

Verify:

agctl version

go install

If you have Go 1.26+ installed:

go install github.com/agenticenv/agent-sdk-go/cli@latest

The binary is written to $(go env GOPATH)/bin — ensure that directory is on your PATH.

Quick start

You need an LLM API key for cloud providers (OpenAI, Anthropic, Gemini, etc.). A config file is optional — set env vars and run:

export AGCTL_LLM_APIKEY=sk-your-key
export AGCTL_LLM_PROVIDER=openai
export AGCTL_LLM_MODEL=gpt-4o

agctl run --prompt "Hello"
agctl chat

Save settings: agctl config edit opens your config in $EDITOR and writes to the path from agctl config path when you save. One command only: agctl --config ~/my-settings.yaml chat or AGCTL_CONFIG=~/my-settings.yaml — partial YAML is fine (see Configuration). In chat, type at You:. Exit with exit, quit, or bye. For local Ollama, you usually omit the API key: AGCTL_LLM_PROVIDER=ollama AGCTL_LLM_MODEL=llama3 agctl chat.

Command reference

Command	Description
`agctl`	Print help
`agctl chat`	Interactive multi-turn session
`agctl run --prompt "…"`	One-shot prompt; also accepts a positional argument or stdin
`agctl version`	Print version
`agctl config path`	Print where your saved config file lives
`agctl config show`	Print your effective config after merge (secrets redacted)
`agctl config edit`	Open config in `$EDITOR`; creates the file on save if it does not exist yet

Global flag: --config / -c / AGCTL_CONFIG — optional YAML file merged on top of defaults and your saved config. Tool approval: In agctl chat, built-in tools prompt Approve? (y/n) before they run. If you enable MCP servers, tools run automatically. agctl run never prompts — it auto-approves all tool calls.

`agctl chat` and `agctl run` flags

These override config for a single invocation (highest precedence):

Flag	Env	Description
`--runtime`	`AGCTL_RUNTIME`	`local` (default), `temporal`, or `restate`
`--provider`	`AGCTL_LLM_PROVIDER`	e.g. `openai`, `anthropic`, `gemini`, `ollama`
`--model`	`AGCTL_LLM_MODEL`	Model name
`--api-key`	`AGCTL_LLM_APIKEY`	LLM API key (prefer env for secrets)
`--llm-usage`	`AGCTL_LLM_USAGE`	Print token usage summary on exit
`--temporal-host`	`AGCTL_TEMPORAL_HOST`	Temporal host when `runtime: temporal`
`--temporal-port`	`AGCTL_TEMPORAL_PORT`	Temporal gRPC port (default `7233`)
`--temporal-namespace`	`AGCTL_TEMPORAL_NAMESPACE`	Namespace (default `default`)
`--temporal-task-queue`	`AGCTL_TEMPORAL_TASKQUEUE`	Task queue (default `agent-sdk-go`)
`--restate-ingress-url`	`AGCTL_RESTATE_INGRESS_URL`	Restate ingress when `runtime: restate`
`--restate-admin-url`	`AGCTL_RESTATE_ADMIN_URL`	Restate admin URL
`--restate-auth-key`	`AGCTL_RESTATE_AUTH_KEY`	Optional ingress auth key
`--restate-endpoint-listen-address`	`AGCTL_RESTATE_ENDPOINT_LISTEN_ADDRESS`	SDK endpoint listen address (default `:9080`)
`--restate-deployment-url`	`AGCTL_RESTATE_DEPLOYMENT_URL`	Callback URL for containerized Restate

Examples

One-shot query

export AGCTL_LLM_APIKEY=sk-your-key
agctl run --prompt "Summarize the benefits of durable agent execution."

With flags instead of env:

agctl run --api-key sk-your-key --provider openai --model gpt-4o --prompt "Hello"

Interactive chat

export AGCTL_LLM_APIKEY=sk-your-key
agctl chat

Override config for one command

agctl --config ~/my-agctl.yaml chat
# or
AGCTL_CONFIG=~/my-agctl.yaml agctl run --prompt "Hello"

Partial files are enough — only include keys you want to change:

# ~/my-agctl.yaml
llm:
  model: gpt-4o-mini
tools:
  weather:
    enabled: false

Temporal runtime

agctl chat --runtime temporal
# optional connection overrides (defaults: localhost:7233, namespace default, task queue agent-sdk-go)
agctl chat --runtime temporal --temporal-host my-temporal.example --temporal-port 7233

Restate runtime

agctl chat --runtime restate
# optional overrides (defaults: ingress http://localhost:8080, admin http://localhost:9070, listen :9080)
agctl chat --runtime restate --restate-deployment-url http://host.docker.internal:9080

See restate-setup.md for a local Restate server.

Configuration

agctl ships with sensible defaults. You can run with env vars only, save a file with config edit, or pass --config for a one-off override. Settings merge in order — later layers win. You only need to set the keys you care about in YAML.

Order	Source
1	Built-in defaults (compiled into the binary)
2	Saved config at `agctl config path` (if the file exists)
3	`--config` / `AGCTL_CONFIG` (file must exist)
4	`AGCTL_*` environment variables
5	`agctl chat` / `agctl run` flags

Config file location (agctl config path):

macOS: ~/Library/Application Support/agctl/config.yaml
Linux: ~/.config/agctl/config.yaml (or $XDG_CONFIG_HOME/agctl/config.yaml)
Windows: %LOCALAPPDATA%\agctl\config.yaml

Run agctl config show to see what is in effect. API keys and tokens print as ***. The temporal / restate blocks appear only when that runtime is selected.

Config schema

Top-level keys:

Key	Description
`runtime`	`local`, `temporal`, or `restate`
`name`	Agent name (default `agctl`)
`system_prompt`	System prompt for the agent
`llm`	Provider, model, API key, base URL
`conversation`	Store backend (`inmem` or `redis`) and limits
`logger`	SDK log level, output, format
`llm_usage`	Print token usage summary on exit
`tools`	Built-in tools — each `enabled: true\|false`
`mcp`	Optional MCP server list
`temporal`	Connection settings when `runtime: temporal`
`restate`	Connection settings when `runtime: restate`

llm

Field	Env	Notes
`provider`	`AGCTL_LLM_PROVIDER`	`openai`, `anthropic`, `gemini`, `deepseek`, `ollama`, …
`apiKey`	`AGCTL_LLM_APIKEY`	Prefer env; not required for local Ollama
`model`	`AGCTL_LLM_MODEL`	e.g. `gpt-4o`
`baseURL`	`AGCTL_LLM_BASEURL`	OpenAI-compatible proxy URL

conversation

Field	Env	Notes
`store`	`AGCTL_CONVERSATION_STORE`	`inmem` (default) or `redis`
`max_size`	—	Max messages stored
`size`	—	Max messages fetched for LLM context
`save_on_iteration`	—	Persist after each tool round
`redis.addr`	`AGCTL_CONVERSATION_REDIS_ADDR`	Required when `store: redis`
`redis.password`	`AGCTL_CONVERSATION_REDIS_PASSWORD`	Optional
`redis.db`	`AGCTL_CONVERSATION_REDIS_DB`	Default `0`

tools — built-in tool names: echo, current_time, random, calculator, weather, wikipedia, search. All default to enabled; set enabled: false to omit from the registry. temporal — only used when runtime: temporal. Defaults if omitted: localhost:7233, namespace default, task queue agent-sdk-go. restate — only used when runtime: restate. Defaults if omitted: ingress http://localhost:8080, admin http://localhost:9070, endpoint listen :9080. logger — SDK/agent logs only; prompts and replies print to the console separately. Default output resolves to a log file under XDG state ($XDG_STATE_HOME/agctl/agctl.log for installed binaries).

Example config.yaml

runtime: local
name: agctl
system_prompt: "You are a helpful agent. Use available tools when they improve accuracy."

llm:
  provider: openai
  apiKey: ""              # prefer AGCTL_LLM_APIKEY
  model: gpt-4o
  baseURL: https://api.openai.com/v1

conversation:
  store: inmem
  max_size: 100
  size: 20
  save_on_iteration: true

logger:
  level: info
  output: logs/agctl.log
  format: json

llm_usage: false

tools:
  echo: { enabled: true }
  calculator: { enabled: true }
  weather: { enabled: false }

# Uncomment when using temporal:
# temporal:
#   host: localhost
#   port: 7233
#   namespace: default
#   taskQueue: agent-sdk-go

# Uncomment when using restate:
# restate:
#   ingressURL: http://localhost:8080
#   adminURL: http://localhost:9070
#   endpointListenAddress: ":9080"

# Optional MCP — see section below
# mcp:
#   servers: [...]

Environment variables

All use the AGCTL_ prefix. They override merged file values. Prefer env for secrets.

Variable	Description
`AGCTL_CONFIG`	Path to optional override YAML
`AGCTL_RUNTIME`	`local`, `temporal`, or `restate`
`AGCTL_NAME`	Agent name
`AGCTL_SYSTEM_PROMPT`	System prompt
`AGCTL_CONVERSATION_STORE`	`inmem` or `redis`
`AGCTL_CONVERSATION_REDIS_ADDR`	Redis address
`AGCTL_CONVERSATION_REDIS_PASSWORD`	Redis password
`AGCTL_CONVERSATION_REDIS_DB`	Redis DB number
`AGCTL_TEMPORAL_HOST`	Temporal server host
`AGCTL_TEMPORAL_PORT`	Temporal gRPC port
`AGCTL_TEMPORAL_NAMESPACE`	Temporal namespace
`AGCTL_TEMPORAL_TASKQUEUE`	Task queue name
`AGCTL_RESTATE_INGRESS_URL`	Restate ingress URL
`AGCTL_RESTATE_ADMIN_URL`	Restate admin URL
`AGCTL_RESTATE_AUTH_KEY`	Restate ingress auth key
`AGCTL_RESTATE_ENDPOINT_LISTEN_ADDRESS`	SDK endpoint listen address
`AGCTL_RESTATE_DEPLOYMENT_URL`	Callback URL for containerized Restate
`AGCTL_LLM_PROVIDER`	LLM provider
`AGCTL_LLM_APIKEY`	LLM API key
`AGCTL_LLM_MODEL`	Model name
`AGCTL_LLM_BASEURL`	API base URL
`AGCTL_LOGGER_LEVEL`	`error`, `warn`, `info`, `debug`
`AGCTL_LOGGER_OUTPUT`	File path, `stdout`, or `stderr`
`AGCTL_LOGGER_FORMAT`	`json` or `text`
`AGCTL_LOGGER_ADD_SOURCE`	`true` / `false`
`AGCTL_LOGGER_TEE_STDERR`	`true` / `false`
`AGCTL_LLM_USAGE`	Print token usage on exit

MCP servers (optional)

Add entries under mcp.servers in your config (via agctl config edit or --config):

mcp:
  servers:
    - enabled: true
      name: filesystem
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
      timeout_seconds: 60
      retry_attempts: 3

Field	Notes
`enabled`	Must be `true` to connect
`name`	Prefix for tools: `mcp_<name>_<tool>`
`transport`	`stdio` (subprocess) or `streamable_http`
`command`, `args`, `env`	For stdio transports
`url`, `bearer_token`, OAuth fields, `headers`	For HTTP transports
`allow_tools`, `block_tools`	Optional tool filters
`timeout_seconds`, `retry_attempts`	Connection tuning

When at least one MCP server is enabled, agctl chat auto-approves MCP tool calls (no per-call prompt). See MCP for how MCP works in the SDK. Run agctl config edit for commented examples of HTTP transport and OAuth fields.

Token usage summary

Set llm_usage: true in config, AGCTL_LLM_USAGE=true, or pass --llm-usage on a single run. Chat prints a session total on exit; run prints after the single turn:

[USAGE] session total
  prompt_tokens:     12120
  completion_tokens: 262
  total_tokens:      12382
  cached_prompt:     12541

When llm.provider is anthropic, the CLI enables prompt caching automatically (unlike the SDK library default — see LLM Providers).

Logging

The console shows your prompts and the agent’s replies. SDK diagnostic logs go to a file by default (logger.output, typically under $XDG_STATE_HOME/agctl/agctl.log). Override with logger.output or AGCTL_LOGGER_OUTPUT (stdout, stderr, or a path).

Troubleshooting

LLM API key required

Cloud providers need a key. Set AGCTL_LLM_APIKEY or llm.apiKey in config. Local Ollama usually does not need a key (AGCTL_LLM_PROVIDER=ollama).

Config file not found

If you pass --config or AGCTL_CONFIG, the path must exist. Check spelling and permissions. To use only defaults + env, omit both.

Saved config file missing

If agctl config path points to a file that does not exist yet, that is expected. agctl still runs with built-in defaults and env vars. Use agctl config edit to create the file, or write YAML at that path yourself.

Env var not applying

Confirm the AGCTL_ prefix and spelling (e.g. AGCTL_LLM_APIKEY, not AGENT_). Env overrides file values but chat/run flags override env for the same field. Run agctl config show to see the merged result.

`--config` partial file seems ignored

Partial YAML only overrides the keys you set. If you also have a saved config file, --config is merged after it, so your override file wins for any keys you specify there. Run agctl config show to confirm the merged result.

Temporal connection errors

Ensure a Temporal server is running and reachable. With --runtime temporal and no temporal: block, defaults are localhost:7233, namespace default, task queue agent-sdk-go. Override via config, env, or --temporal-* flags.

Restate connection errors

Ensure a Restate server is running and reachable. With --runtime restate and no restate: block, defaults are ingress http://localhost:8080, admin http://localhost:9070, listen :9080. See restate-setup.md. When Restate runs in Docker, set --restate-deployment-url http://host.docker.internal:9080.

MCP server fails to start

Check command and args for stdio servers, or url for HTTP. Increase timeout_seconds. Inspect SDK logs (logger.output / XDG state log file).

Quickstart

Build an agent in your own Go application

Configuration

SDK configuration options the CLI uses under the hood

Overview

Getting Started

Runtimes

Features

Advanced

Observability

Testing & Evaluation

Production

Reference Apps

Install

GitHub Releases (recommended)

go install

Quick start

Command reference

`agctl chat` and `agctl run` flags

Examples

One-shot query

Interactive chat

Override config for one command

Temporal runtime

Restate runtime

Configuration

Config schema

Example config.yaml

Environment variables

MCP servers (optional)

Token usage summary

Logging

Troubleshooting

LLM API key required

Config file not found

Saved config file missing

Env var not applying

`--config` partial file seems ignored

Temporal connection errors

Restate connection errors

MCP server fails to start

Quickstart

Configuration

​Install

​GitHub Releases (recommended)

​go install

​Quick start

​Command reference

​agctl chat and agctl run flags

​Examples

​One-shot query

​Interactive chat

​Override config for one command

​Temporal runtime

​Restate runtime

​Configuration

​Config schema

​Example config.yaml

​Environment variables

​MCP servers (optional)

​Token usage summary

​Logging

​Troubleshooting

​LLM API key required

​Config file not found

​Saved config file missing

​Env var not applying

​--config partial file seems ignored

​Temporal connection errors

​Restate connection errors

​MCP server fails to start

​Related

Quickstart

Configuration

Install

GitHub Releases (recommended)

go install

Quick start

Command reference

`agctl chat` and `agctl run` flags

Examples

One-shot query

Interactive chat

Override config for one command

Temporal runtime

Restate runtime

Configuration

Config schema

Example config.yaml

Environment variables

MCP servers (optional)

Token usage summary

Logging

Troubleshooting

LLM API key required

Config file not found

Saved config file missing

Env var not applying

`--config` partial file seems ignored

Temporal connection errors

Restate connection errors

MCP server fails to start

Related