cmd

CLI

The agentctl CLI uses agent-sdk-go and therefore needs a running Temporal server — same as the library examples.

Interactive conversation mode. Type prompts, get responses. Type exit, quit, or bye to end.

Configuration

1. Copy the sample config and add your values:

   cp cmd/config.sample.yaml cmd/config.yaml
   

2. Edit cmd/config.yaml with your Temporal host, LLM provider, API key, and model.

3. Optional: Use environment variables to override (keeps secrets out of the config file):

   export AGENT_LLM_APIKEY=sk-your-key
   export AGENT_LLM_PROVIDER=openai
   export AGENT_LLM_MODEL=gpt-4o
   go run ./cmd
   

• config.sample.yaml — template (committed to repo)
• config.yaml — your config (gitignored; do not commit)

Prerequisites

Temporal server must be running. Start a local dev server with Docker:

docker run --rm -p 7233:7233 -p 8233:8233 temporalio/temporal:latest server start-dev --ip 0.0.0.0

• Temporal service: localhost:7233
• Web UI: http://localhost:8233

Or use Temporal CLI: temporal server start-dev.

For production or self-hosted (Docker Compose, Kubernetes): Temporal Cloud | Self-hosted deployment

The CLI uses temporal.host, temporal.port, temporal.namespace from config.yaml (default: localhost, 7233, default). Override with AGENT_TEMPORAL_HOST, AGENT_TEMPORAL_PORT, AGENT_TEMPORAL_NAMESPACE if Temporal runs elsewhere.

Run

go run ./cmd

Or with a custom config path:

go run ./cmd -config cmd/config.yaml

Build

From project root:

make build
./cmd/bin/agentctl

Or build manually with an embedded version (matches make build, which uses git describe):

go build -ldflags "-X main.version=$(git describe --tags --always --dirty 2>/dev/null || echo dev)" -o cmd/bin/agentctl ./cmd

A plain go build ./cmd leaves the version as dev until you pass -ldflags. Release binaries from GitHub get the tag via GoReleaser (see .goreleaser.yaml, -X main.version=<git tag>).

The cmd/bin/ directory is gitignored.

Install

Install agentctl to $(go env GOPATH)/bin so you can run it from anywhere (ensure that directory is in your PATH):

make install
agentctl -config cmd/config.yaml

Config file and env vars

Config is loaded from cmd/config.yaml (default). If the file does not exist, defaults plus env vars are used.

Logging

The CLI shows only user prompts and agent responses on the console. Internal logs go to a file.

• Default log file: cmd/logs/agent.log (resolved from project root; gitignored)
• Configure: Set logger.output in config.yaml or AGENT_LOGGER_OUTPUT
• Directories: logs/ and cmd/bin/ are gitignored