Configuration¶
Every setting of the a2a CLI, with its flag, environment variable, config key, type, default and the sources it can come from. Every flag except --stream, --help, --version and --config can be set from the environment or a configuration file. Configuration Layers explains how values are resolved, and the Configuration guide shows everyday use.
Global settings¶
These apply to every command. The environment variable is A2ACLI_ followed by the flag name in upper case with - replaced by _. In files, the key is the flag name or the environment variable name.
| Flag | Environment variable | Type | Default | Discovered .env |
Notes |
|---|---|---|---|---|---|
-a, --agent-card |
A2ACLI_AGENT_CARD |
host, URL, path, identifier or contact | yes | Card reference. See reference normalization. Exclusive with --endpoint. |
|
--catalog |
A2ACLI_CATALOG |
name or URL | yes | AI Catalog to look the --agent-card identifier up in: a registered name, or a catalog URL. See AI Catalogs. Experimental. |
|
-e, --endpoint |
A2ACLI_ENDPOINT |
URL | yes | Interface URL; skips the card. Needs exactly one --transport. |
|
--transport |
A2ACLI_TRANSPORT |
list | yes | rest, jsonrpc, grpc or a plugin name, most preferred first. Comma separated in the environment and .env. |
|
--a2a-version |
A2ACLI_A2A_VERSION |
string | yes | 1.0 or 0.3 registers only that version's transports. Unset registers both. |
|
--svc-param |
A2ACLI_SVC_PARAM |
repeatable key=value or key:value |
yes | Request header or gRPC metadata. Split on the first = or :. In the environment and .env, one entry; use a YAML or JSON list for several. |
|
--auth |
A2ACLI_AUTH |
string | yes | Same as --svc-param Authorization=<value>. |
|
--tenant |
A2ACLI_TENANT |
string | yes | Tenant on every request. | |
--timeout |
A2ACLI_TIMEOUT |
duration | 30s |
yes | Whole request, or time between events when streaming. See Streaming and Timeouts. |
-o, --output |
A2ACLI_OUTPUT |
text, json, jsonl |
text |
yes | See Output. |
-v, --verbose |
A2ACLI_VERBOSE |
bool | false |
yes | Progress lines on stderr, prefixed #. |
--insecure |
A2ACLI_INSECURE |
bool | false |
yes | Plaintext gRPC. |
--ca-cert |
A2ACLI_CA_CERT |
path | no | Trust only the PEM certificates in the file, for HTTP and gRPC. Read when a command connects. | |
--unix-socket |
A2ACLI_UNIX_SOCKET |
path | no | Send every HTTP request and gRPC connection through the socket. | |
--credential-helper |
A2ACLI_CREDENTIAL_HELPER |
list of helpers | no | [scope=]path on the command line and in the environment; {scope, command} objects in YAML and JSON. See below. |
|
--config |
never read | path | Use this file as the local file in place of the discovered .env. |
||
A2ACLI_PLUGINS_ENABLED |
bool | false |
yes | Config key plugins-enabled. Discover command plugins. Not read from the --config file. |
"Discovered .env" is the .env found by walking up from the working directory. A setting marked no is ignored there with a warning; it can still come from the flag, the environment, the user config.yaml, the global .env or a file passed with --config.
Booleans accept the values of Go's strconv.ParseBool: 1, t, T, true, TRUE, True, 0, f, F, false, FALSE, False. Durations use Go's syntax, such as 500ms, 30s, 5m, 1h30m; in YAML and JSON write them as strings.
Command settings¶
The flags of each command bind the same way, through A2ACLI_<NAME> or the flag name in a file. A value applies to every command that has a flag of that name, and is ignored by commands that don't. An invalid value fails only the commands that have the flag.
| Flag | Environment variable | Commands |
|---|---|---|
--async |
A2ACLI_ASYNC |
send |
--context-id |
A2ACLI_CONTEXT_ID |
send, chat |
--task-id |
A2ACLI_TASK_ID |
send, chat |
--history |
A2ACLI_HISTORY |
send, task get, task list |
--poll-interval |
A2ACLI_POLL_INTERVAL |
send, chat, task get |
--save-fileparts |
A2ACLI_SAVE_FILEPARTS |
send, task get, task subscribe |
--request-payload |
A2ACLI_REQUEST_PAYLOAD |
send |
--text-part, --file-part, --data-part, --media-type |
A2ACLI_TEXT_PART, ... |
send |
--metadata |
A2ACLI_METADATA |
send, task cancel |
--wait |
A2ACLI_WAIT |
task get |
--context, --status, --since, --with-artifacts |
A2ACLI_CONTEXT, ... |
task list |
--limit, --page-token |
A2ACLI_LIMIT, A2ACLI_PAGE_TOKEN |
task list, task push-config list |
--url, --id, --token, --auth-scheme, --auth-credentials |
A2ACLI_URL, ... |
task push-config create |
--extended |
A2ACLI_EXTENDED |
card get |
--reveal |
A2ACLI_REVEAL |
auth get |
--no-descriptions |
A2ACLI_NO_DESCRIPTIONS |
completion subcommands |
--discovery, --discovery-allow-host, --discovery-scan-tools |
A2ACLI_DISCOVERY, ... |
hook; see Coding Agents. discovery-allow-host is not read from a discovered .env. |
--stream is never read from configuration. The command reference describes each flag.
Warning
Message flags bind too. A2ACLI_FILE_PART or A2ACLI_TEXT_PART adds a part to every message send builds, and A2ACLI_TASK_ID makes every send continue the same task. Settings with names as generic as A2ACLI_URL or A2ACLI_TOKEN apply to task push-config create.
config show lists the global settings only.
Precedence¶
The first source with a value wins:
- Command-line flag
- Environment variable
- Local file: the
--configfile, or else the nearest.envwalking up from the working directory ~/.config/a2a-cli/config.yaml~/.config/a2a-cli/.env- Flag default
Files¶
| File | Format | Notes |
|---|---|---|
.env in the working directory or a parent |
dotenv | Discovered; protected settings ignored. Not read when --config is set. |
--config <path> |
by extension | Replaces the discovered .env. Must exist. |
~/.config/a2a-cli/config.yaml |
YAML | User config. a2a plugin set-enabled writes it, mode 0600. |
~/.config/a2a-cli/.env |
dotenv | Global defaults. |
~ is the home directory from Go's os.UserHomeDir: $HOME on Unix, %USERPROFILE% on Windows. XDG_CONFIG_HOME is not used.
The format of a --config file comes from its extension:
| Extension | Format |
|---|---|
.json |
JSON object |
.yaml, .yml |
YAML mapping |
.env |
dotenv |
| anything else | JSON, then YAML, then dotenv; the first that parses as a mapping |
An empty file is valid in every format. Keys that match no flag are ignored.
dotenv¶
dotenv files are parsed by the github.com/joho/godotenv library:
- One
KEY=valueper line.KEY: valuealso works. - Keys contain only letters, digits,
_and.. Any other character, such as-inagent-card=, is a parse error that fails every command, so use the environment variable names. - A leading
exportis ignored. - Lines starting with
#are comments, and so is#and anything after it in an unquoted value. - Single quotes keep the value as is. Double quotes allow
\nescapes. ${KEY}and$KEYin unquoted and double-quoted values expand to a key defined earlier in the same file. The process environment is not used; an unknown key expands to nothing.- Every value is a string. For
--transport, the string is split on commas.
# .env
A2ACLI_AGENT_CARD=https://agent.example.com
A2ACLI_TRANSPORT=jsonrpc,rest
A2ACLI_TIMEOUT=60s
export A2ACLI_TENANT="my team"
YAML and JSON¶
Use the flag name or the environment variable name as the key, with native types. Lists set repeatable flags.
agent-card: https://agent.example.com
transport: [jsonrpc, rest]
timeout: 60s
insecure: false
tenant: my-team
svc-param:
- "Authorization=Bearer <token>"
- "X-Client-ID=cli-app"
plugins-enabled: true
{
"agent-card": "https://agent.example.com",
"transport": ["jsonrpc", "rest"],
"timeout": "60s",
"svc-param": ["X-Client-ID=cli-app"]
}
Numbers and booleans are converted to strings before they are parsed, so timeout: 60 is the invalid duration 60.
Credential helper entries¶
In YAML and JSON, credential-helper is a list of objects:
| Key | Type | Required | Meaning |
|---|---|---|---|
command |
list of strings | yes | Program and arguments; get is appended when it runs |
scope |
string | no | host or *.domain, without a port. Omit for every host. |
Other keys are an error.
credential-helper:
- command: [a2a-serve, credential]
- scope: "*.corp.example.com"
command: [/usr/local/bin/corp-helper, --profile, work]
A single string, and the flag and environment variable, take [scope=]path: one program without arguments, with an optional scope before the first =. Each --credential-helper flag adds a helper; the environment variable holds one. See Credential Helpers.