> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenticenv.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Run agents interactively from the terminal using agentctl with a YAML config file

**`agentctl`** is the interactive REPL for Agent SDK for Go. Type prompts and receive agent responses. It uses the same SDK as your application code and supports both in-process and Temporal runtimes via a YAML config file.

<Note>
  **`agentctl` is not the Go library.** Install the SDK with `go get github.com/agenticenv/agent-sdk-go`. Install `agentctl` separately — download a release binary or build from source.
</Note>

## Install agentctl

### Option 1 — Release binary (recommended)

Pre-built binaries for Linux, macOS, and Windows (amd64 and arm64) are on [GitHub Releases](https://github.com/agenticenv/agent-sdk-go/releases).

1. Open the latest release
2. Download the archive for your platform from **Assets**
3. Extract and add `agentctl` to your `PATH`

### Option 2 — Build from source

```bash theme={null}
make build
./cmd/bin/agentctl

# Or install to $GOPATH/bin:
make install
agentctl -config cmd/config.yaml
```

### Option 3 — Run without building (development)

From a cloned repository:

```bash theme={null}
go run ./cmd
```

Compiles and runs on each invocation — useful during development.

## Quick start

```bash theme={null}
# 1. Copy the sample config
cp cmd/config.sample.yaml config.yaml
# Edit config.yaml — set llm.apiKey or use AGENT_LLM_APIKEY

# 2. Run the CLI
agentctl -config config.yaml
```

If you use a release binary without cloning the repo, copy `config.sample.yaml` from the release assets into your working directory.

Type prompts at the `>` prompt. Enter `exit`, `quit`, or `bye` to end the session.

## Configuration file

| File                     | Purpose                                    |
| ------------------------ | ------------------------------------------ |
| `cmd/config.sample.yaml` | Template — safe to commit                  |
| `cmd/config.yaml`        | Your config — gitignored, copy from sample |

Run with a custom path:

```bash theme={null}
agentctl -config /path/to/config.yaml
```

### Runtime selection

Set `runtime` in `config.yaml`:

| Value             | Behavior                                               |
| ----------------- | ------------------------------------------------------ |
| `local` (default) | In-process — no Temporal server required               |
| `temporal`        | Durable execution — requires a running Temporal server |

Override per invocation:

```bash theme={null}
AGENT_RUNTIME=temporal agentctl -config config.yaml
```

### Minimal config.yaml

```yaml theme={null}
runtime: local

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

temporal:
  host: localhost
  port: 7233
  namespace: default
  taskQueue: agent-sdk-go

logger:
  level: info
  output: logs/agent.log
  format: json
```

## Environment variables

Environment variables override config file values. Prefer them for secrets.

| Variable                   | Description                                     |
| -------------------------- | ----------------------------------------------- |
| `AGENT_RUNTIME`            | `local` or `temporal`                           |
| `AGENT_TEMPORAL_HOST`      | Temporal server host                            |
| `AGENT_TEMPORAL_PORT`      | Temporal gRPC port                              |
| `AGENT_TEMPORAL_NAMESPACE` | Temporal namespace                              |
| `AGENT_TEMPORAL_TASKQUEUE` | Task queue name                                 |
| `AGENT_LLM_PROVIDER`       | `openai`, `anthropic`, or `gemini`              |
| `AGENT_LLM_APIKEY`         | LLM API key                                     |
| `AGENT_LLM_MODEL`          | Model name                                      |
| `AGENT_LLM_BASEURL`        | Optional base URL for OpenAI-compatible proxies |
| `AGENT_LOGGER_LEVEL`       | `error`, `warn`, `info`, `debug`                |
| `AGENT_LOGGER_OUTPUT`      | Log file path, `stdout`, or `stderr`            |

```bash theme={null}
export AGENT_LLM_APIKEY=sk-your-key
export AGENT_LLM_PROVIDER=openai
export AGENT_LLM_MODEL=gpt-4o
agentctl -config config.yaml
```

## MCP servers (optional)

Add `mcp.servers` entries to `config.yaml` to connect MCP tool servers. When at least one server is enabled, the CLI registers [`WithMCPConfig`](/features/mcp) and [`AutoToolApprovalPolicy`](/features/approvals) so MCP tools run without per-call approval in the REPL.

```yaml theme={null}
mcp:
  servers:
    - enabled: true
      name: filesystem
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
```

Each entry supports: `enabled`, `name`, `transport` (`stdio` or `streamable_http`), `command`/`args` (stdio) or `url`/`bearer_token` (HTTP), and optional `timeout_seconds`, `retry_attempts`, `allow_tools`, `block_tools`.

See `cmd/config.sample.yaml` for HTTP transport, OAuth, and tool filter examples.

## SDK vs CLI

|             | SDK (library)                                      | CLI (`agentctl`)                        |
| ----------- | -------------------------------------------------- | --------------------------------------- |
| **Install** | `go get github.com/agenticenv/agent-sdk-go@latest` | Download release binary or `make build` |
| **Use**     | Import `pkg/agent` in your Go application          | Interactive REPL from the terminal      |
| **Config**  | Go code — `NewAgent(...)` options                  | YAML file + env vars                    |

Both are published from the same repository. Pin the SDK version in your `go.mod`; pin the CLI by downloading the matching release tag.

## Logging

`agentctl` prints **only user prompts and agent responses** on the console. Internal SDK logs go to a file.

* Default: `cmd/logs/agent.log` (gitignored)
* Override: `logger.output` in config or `AGENT_LOGGER_OUTPUT`

## Related

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/getting-started/quickstart">
    Build an agent in your own Go application
  </Card>

  <Card title="Configuration" icon="sliders" href="/getting-started/configuration">
    All SDK options the CLI uses under the hood
  </Card>

  <Card title="MCP" icon="plug" href="/features/mcp">
    Connect MCP servers programmatically
  </Card>

  <Card title="Running Examples" icon="play" href="/examples/running-examples">
    Run SDK examples from the repository
  </Card>
</CardGroup>