# 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`](/agent-manager/docs/v1.0.0-rc1/reference/cli/agent/.md#amctl-agent-create). The command group is also available under the `llm-providers` alias.

## Subcommands[​](#subcommands "Direct link to Subcommands")

| Command                                | Purpose                               |
| -------------------------------------- | ------------------------------------- |
| [`create`](#amctl-llm-provider-create) | Create an LLM provider                |
| [`list`](#amctl-llm-provider-list)     | List LLM providers in an organization |
| [`delete`](#amctl-llm-provider-delete) | Delete an LLM provider                |

## Options inherited from parent commands[​](#options-inherited-from-parent-commands "Direct link to Options inherited from parent commands")

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

***

## amctl llm-provider create[​](#amctl-llm-provider-create "Direct link to 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[​](#arguments "Direct link to 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[​](#examples "Direct link to 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[​](#options "Direct link to 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`](/agent-manager/docs/v1.0.0-rc1/reference/cli/gateway/.md). |

### Built-in templates[​](#built-in-templates "Direct link to 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[​](#template-inheritance-and-credentials "Direct link to 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`](/agent-manager/docs/v1.0.0-rc1/reference/cli/gateway/.md#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](/agent-manager/docs/v1.0.0-rc1/guides/register-llm-service-provider/.md)).
* 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[​](#amctl-llm-provider-list "Direct link to 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[​](#example "Direct link to Example")

```
amctl llm-provider list



# As JSON for downstream parsing

amctl llm-provider list --json | jq '.data.providers[].id'
```

***

## amctl llm-provider delete[​](#amctl-llm-provider-delete "Direct link to 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[​](#arguments-1 "Direct link to Arguments")

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

### Options[​](#options-1 "Direct link to Options")

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

### Examples[​](#examples-1 "Direct link to 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[​](#when-deletion-is-refused "Direct link to 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`](/agent-manager/docs/v1.0.0-rc1/reference/cli/agent/.md).

## See Also[​](#see-also "Direct link to See Also")

* [`amctl gateway list`](/agent-manager/docs/v1.0.0-rc1/reference/cli/gateway/.md#amctl-gateway-list) — find the gateway names and UUIDs `--gateways` accepts

* [`amctl agent create`](/agent-manager/docs/v1.0.0-rc1/reference/cli/agent/.md#amctl-agent-create) — attach a provider to an agent with `--llm-provider`

* [Register an LLM Service Provider](/agent-manager/docs/v1.0.0-rc1/guides/register-llm-service-provider/.md) — console walkthrough and per-provider settings

* [Configure LLM Providers for an Agent](/agent-manager/docs/v1.0.0-rc1/guides/configure-agent-llm-configuration/.md) — attaching providers to platform and external agents