Lesson 2: Configuration¶
In lesson 1 you saved the agent's address in a .env file. That is one of several places a2a reads settings from. In this lesson you set the same setting in each of them, and use a2a config show to see which one won and why.

What you'll learn¶
- The places a setting can come from, and their order
- How flag names map to
A2ACLI_*variables and config file keys - How
a2a config showreports each value and its source - Which settings a project's
.envcan't set, and why
Prerequisites¶
The agent from lesson 1, still running. If you stopped it, start it again in the background and update .env:
cd ~/a2a-lessons/agent && a2a-serve start --detach
cd ~/a2a-lessons && echo "A2ACLI_AGENT_CARD=$(a2a-serve status --dir agent --url=local)" > .env
Run everything below in ~/a2a-lessons.
Step 1: See the current configuration¶
a2a config show
SETTING VALUE SOURCE
a2a-version (unset) default
agent-card http://127.0.0.1:43229 local-file
auth <redacted> default
ca-cert (unset) default
catalog (unset) default
credential-helper a2a-serve credential user-file
endpoint (unset) default
insecure false default
output text default
svc-param (unset) default
tenant (unset) default
timeout 30s default
transport (unset) default
unix-socket (unset) default
verbose false default
Every global flag is listed with its value and where the value came from. Two are already set: agent-card from your .env (local-file), and credential-helper from ~/.config/a2a-cli/config.yaml (user-file), where a2a-serve doctor --fix put it. Lesson 5 explains the helper.
Step 2: Set one value in four places¶
Take --timeout, which bounds how long a2a waits. Its default is 30s.
A config file for all your commands. ~/.config/a2a-cli/config.yaml uses the flag names as keys:
echo "timeout: 45s" >> ~/.config/a2a-cli/config.yaml
a2a config show | grep timeout
timeout 45s user-file
A project file. In a .env file, the key is the flag name in upper snake case with an A2ACLI_ prefix:
echo "A2ACLI_TIMEOUT=1m" >> .env
a2a config show | grep timeout
timeout 1m local-file
An environment variable for the rest of this shell session:
export A2ACLI_TIMEOUT=2m
a2a config show | grep timeout
timeout 2m env
A flag for one command:
a2a config show --timeout 3m | grep timeout
timeout 3m0s flag
Each one beat the one before. A flag's value prints the way a2a parsed it, here 3m0s; values from files and variables print as written. The full order, first match wins:
- a flag
- an
A2ACLI_*environment variable - the local file: the one
--confignames, or the nearest.envat or above the working directory ~/.config/a2a-cli/config.yaml~/.config/a2a-cli/.env- the built-in default
Clean up before moving on:
unset A2ACLI_TIMEOUT
sed -i.bak '/^timeout:/d' ~/.config/a2a-cli/config.yaml
sed -i.bak '/^A2ACLI_TIMEOUT=/d' .env
rm ~/.config/a2a-cli/config.yaml.bak .env.bak
Step 3: Pick a file with --config¶
--config loads a file in place of .env. It can be .env, YAML or JSON, which suits settings you switch between, such as one file per agent:
cat > verbose.yaml <<'EOF'
verbose: true
output: json
EOF
a2a --config verbose.yaml config show | jq -r '.[] | select(.source == "local-file") | "\(.name)=\(.value) from \(.path)"'
output=json from verbose.yaml
verbose=true from verbose.yaml
verbose.yaml sets output: json, so config show printed JSON, which includes the path each value came from. The agent card is unset now, because verbose.yaml replaced .env.
Step 4: Settings a project can't set¶
A .env file can come with a repository you cloned. Three settings would let it take over your requests: --credential-helper runs a program, --unix-socket redirects every connection, and --ca-cert decides which certificates to trust. a2a ignores them in a .env it found by walking up, and says so:
echo "A2ACLI_CA_CERT=/tmp/evil.pem" >> .env
a2a config show | grep ca-cert
sed -i.bak '/^A2ACLI_CA_CERT=/d' .env && rm .env.bak
warning: ignoring ca-cert from /home/you/a2a-lessons/.env; pass --config /home/you/a2a-lessons/.env to use it
ca-cert (unset) default
Set them as flags, variables, in config.yaml, or in a file you pass with --config.
Recap¶
- Every flag has an
A2ACLI_*variable and a config file key. - Flags beat variables, variables beat files, and the project file beats your user files.
a2a config showtells you each value and its source;-o jsonadds the file path.--stream,--config,--helpand--versiononly work as flags.
Next¶
Lesson 3 sends richer messages and follows tasks that take a while.