amctl llm-provider

Manage LLM providers in an organization — create, list, and delete connections to upstream LLM APIs.

amctl llm-provider [command]

LLM providers are organization-level resources that represent connections to upstream LLM APIs (OpenAI, Anthropic, AWS Bedrock, …). Once created, a provider is exposed through an AI Gateway and can be attached to agents in any project in the organization — see amctl agent create. The command group is also available under the llm-providers alias.

Subcommands

Command	Purpose
create	Create an LLM provider
list	List LLM providers in an organization
delete	Delete an LLM provider

Options inherited from parent commands

Name	Description
--org	Override the active organization.
--json	Output as JSON envelopes.

---

amctl llm-provider create

Create an LLM provider in the active organization from a built-in or custom template.

amctl llm-provider create <id> [flags]

The endpoint URL and auth scheme are inherited from the chosen --template; override them with --upstream-url / --auth-type / --auth-header only when needed. Supply the provider credential with --api-key-stdin (recommended) or --api-key.

Arguments

Name	Description
<id>	Resource handle for the provider. Must be 1–255 characters and contain only letters, digits, -, or _. Used to reference the provider elsewhere (for example, amctl agent create --llm-provider <id>).

Examples

# OpenAI provider, API key read from stdin (recommended — keeps it out of shell history)
echo "$OPENAI_API_KEY" | amctl llm-provider create prod-openai \
  --display-name "Production OpenAI" \
  --template openai \
  --api-key-stdin

# Anthropic provider that overrides the template's upstream endpoint
amctl llm-provider create prod-anthropic \
  --display-name "Production Anthropic" \
  --template anthropic \
  --upstream-url https://api.anthropic.com \
  --api-key-stdin < anthropic-key.txt

# Deploy the provider to specific AI Gateways at creation time, by name or UUID
echo "$OPENAI_API_KEY" | amctl llm-provider create shared-openai \
  --display-name "Shared OpenAI" \
  --template openai \
  --api-key-stdin \
  --gateways api-platform-default-default

echo "$OPENAI_API_KEY" | amctl llm-provider create shared-openai \
  --display-name "Shared OpenAI" \
  --template openai \
  --api-key-stdin \
  --gateways 550e8400-e29b-41d4-a716-446655440000

# Provider whose template needs no credential
amctl llm-provider create internal-proxy \
  --display-name "Internal Proxy" \
  --template openai \
  --upstream-url https://llm.internal.acme \
  --auth-type none

Options

Name	Type	Default	Description
--display-name	string	required	Human-readable display name.
--template	string	required	Provider template handle, e.g. openai, anthropic, mistralai. Tab-completes the live set for your org.
--version	string	v1.0	Provider version. Must match ^v\d+\.\d+$.
--context	string	/	API context path. Must start with / and must not end with / (except the root path).
--description	string	(none)	Provider description.
--upstream-url	string	(template default)	Override the template's upstream endpoint URL.
--auth-type	string	api-key	Upstream auth type: api-key, basic, bearer, or none.
--auth-header	string	(template default)	Override the template's auth header name.
--api-key	string	(none)	Provider API key. Leaks into shell history — prefer --api-key-stdin.
--api-key-stdin	bool	false	Read the provider API key from stdin.
--access-mode	string	allow_all	Route access control for the deployed proxy: allow_all or deny_all. A proxy deployed with deny_all accepts no requests.
--gateways	strings	(none)	AI Gateway names or UUIDs to deploy the provider to. Repeatable, or comma-separated. Tab-completes from amctl gateway list.

Built-in templates

--template accepts these built-in handles:

anthropic, awsbedrock, azure-openai, azureai-foundry, gemini, mistralai, openai

Tab completion on --template lists the live set — built-in handles plus any custom templates registered for your organization.

Template inheritance and credentials

• A provider inherits the template's upstream URL, auth scheme, and auth header. The upstream block is sent only when you supply --upstream-url, --auth-type, or --auth-header, or a credential — otherwise creation defers entirely to the template.
• --api-key and --api-key-stdin are mutually exclusive.
• An API key cannot be combined with --auth-type none.
• A provider must be associated with at least one AI Gateway to be callable by agents. Pass --gateways at creation with gateway names or UUIDs — amctl gateway list shows both, along with the placement role and environment each gateway carries, and tab completion on --gateways lists them. Gateways can also be associated later from the console (see Register an LLM Service Provider).
• Only EGRESS and BOTH gateways can host an LLM proxy, and no two gateways passed to one provider may share an environment.

tip

Reading the key from stdin keeps it out of your shell history and process list. --api-key-stdin accepts a piped value (echo "$KEY" | …) or a redirected file (… < key.txt).

---

amctl llm-provider list

List the LLM providers in the active organization.

amctl llm-provider list

Returns up to 50 providers. The default text output is a table with id, name, template, status, and created columns; --json returns the raw response.

Example

amctl llm-provider list

# As JSON for downstream parsing
amctl llm-provider list --json | jq '.data.providers[].id'

---

amctl llm-provider delete

Delete an LLM provider. Asks for confirmation unless --yes is set; when stdin is not a terminal, --yes is required.

amctl llm-provider delete <provider> [flags]

Arguments

Name	Description
<provider>	Provider handle (id) or UUID. Tab-completes existing providers in the org.

Options

Name	Short	Type	Default	Description
--yes	-y	bool	false	Skip the confirmation prompt.

Examples

# Delete by handle, with confirmation
amctl llm-provider delete prod-openai

# Delete without prompting (also required in non-interactive shells)
amctl llm-provider delete prod-openai --yes

When deletion is refused

The provider is undeployed from each of its gateways first, then removed. Deletion is refused while anything still references the provider — an LLM proxy, or an agent's LLM configuration:

X cannot delete LLM provider: it has associated LLM proxies. Please delete all proxies
  before deleting the provider

Remove the dependents first. For an agent binding, that is amctl agent llm unset.

See Also

• amctl gateway list — find the gateway names and UUIDs --gateways accepts

• amctl agent create — attach a provider to an agent with --llm-provider

• Register an LLM Service Provider — console walkthrough and per-provider settings

• Configure LLM Providers for an Agent — attaching providers to platform and external agents