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

# Profiles

> Create and manage ax CLI profiles for Arize AX, including self-hosted and on-premise endpoint configuration.

The `ax profiles` commands let you create and manage named configuration profiles. Each profile stores an API key, routing settings, and output preferences. The active profile is used by all other `ax` commands.

## `ax profiles list`

List all available configuration profiles. The active profile is marked with a dot.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles list [--verbose]
```

| Option | Description |
| - | - |
| `--verbose`, `-v` | Enable verbose logs |

**Example:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles list
```

## `ax profiles create`

Create a new configuration profile. Runs interactively by default; use flags or `--from-file` to skip prompts.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles create [<profile-name>] [--api-key <key>] [--auth-method <method>] [--region <region>] [--single-host <host>] [--single-port <port>] [--output-format <format>] [--from-file <path>]
```

| Option | Description |
| - | - |
| `--api-key` | Arize API key |
| `--auth-method` | Authentication method: `api-key` or `oauth`. If omitted, prompts interactively. |
| `--region` | Routing region (e.g. `us-east-1b`) |
| `--single-host` | Single endpoint host for on-prem deployments (e.g. `arize.yourcompany.com`) |
| `--single-port` | Single endpoint port for on-prem deployments (e.g. `443`) |
| `--output-format` | Output format: `table`, `json`, `csv`, `parquet` |
| `--from-file`, `-f` | Path to a TOML config file to load values from |
| `--verbose`, `-v` | Enable verbose logs |

Precedence (highest to lowest): CLI flags > `--from-file` > interactive prompts.

If no `default` profile exists, the interactive prompt pre-fills the profile name as `default`; otherwise you must enter a name. Detects existing `ARIZE_*` environment variables when running interactively (only when neither flags nor `--from-file` are used).

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
# Interactive setup
ax profiles create

# Non-interactive with flags
ax profiles create my-profile --api-key ak_abc123

# From a TOML file
ax profiles create staging --from-file ./staging.toml
```

## `ax profiles show`

Show configuration for a profile. By default shows environment variable references like `${ARIZE_API_KEY}` without expanding them.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles show [<profile>] [--all] [--expand]
```

| Option | Description |
| - | - |
| `--all` | Show all sections including defaults |
| `--expand` | Expand environment variable references to their actual values |
| `--verbose`, `-v` | Enable verbose logs |

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
# Show the active profile
ax profiles show

# Show a named profile with all sections expanded
ax profiles show my-profile --all --expand
```

## `ax profiles update`

Update an existing profile. With `--from-file`, the profile is replaced by the file contents (flags are applied on top). With flags only, specified fields are updated and all others are preserved.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles update [<profile>] [--api-key <key>] [--region <region>] [--single-host <host>] [--single-port <port>] [--output-format <format>] [--from-file <path>]
```

| Option | Description |
| - | - |
| `--api-key` | New Arize API key |
| `--region` | New routing region |
| `--single-host` | Single endpoint host for on-prem deployments |
| `--single-port` | Single endpoint port for on-prem deployments |
| `--output-format` | New output format |
| `--from-file`, `-f` | Replace profile with values from this TOML file |
| `--verbose`, `-v` | Enable verbose logs |

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
# Update the active profile's API key
ax profiles update --api-key ak_new123

# Update a named profile from a file
ax profiles update staging --from-file ./staging.toml
```

## `ax profiles delete`

Delete a configuration profile.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles delete <profile> [--force]
```

| Option | Description |
| - | - |
| `--force`, `-f` | Skip the confirmation prompt |
| `--verbose`, `-v` | Enable verbose logs |

**Examples:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles delete old-profile
ax profiles delete old-profile --force
```

## `ax profiles use`

Switch to a different configuration profile. Makes the specified profile active for all future commands.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles use <profile> [--verbose]
```

| Option | Description |
| - | - |
| `--verbose`, `-v` | Enable verbose logs |

**Example:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles use staging
```

## `ax profiles validate`

Validate a configuration profile. Checks for missing or incorrect configuration and reports any issues.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles validate [<profile>] [--verbose]
```

| Option | Description |
| - | - |
| `--verbose`, `-v` | Enable verbose logs |

**Example:**

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles validate my-profile
```

## Self-Hosted / On-Premise Configuration

When using the CLI with a self-hosted or on-premise Arize AX deployment, you need to point the profile at your private endpoints instead of the default Arize SaaS hosts.

The CLI supports several **mutually exclusive** endpoint override strategies. Use only one at a time:

| Strategy | When to use | TOML fields |
| - | - | - |
| **Single endpoint** | All services behind one host/LB (typical on-prem) | `single_host`, `single_port` |
| **Private Connect** | Private link with a shared base domain | `base_domain` |
| **Per-endpoint** | Separate hosts for API, OTLP, and Flight | `api_host`, `otlp_host`, `flight_host`, etc. |

<Warning>
  These strategies are mutually exclusive. `single_host`/`single_port`, and `base_domain` are mutually exclusive. Set only one.
  If you set `single_host`/`single_port`, the per-endpoint fields (`api_host`, `otlp_host`, `flight_host`) are ignored.
</Warning>

### Interactive setup (recommended)

Run `ax profiles create` and choose **Advanced** configuration mode. You will be prompted to select a single-endpoint or multi-endpoint layout and enter your host(s).

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles create my-onprem
# Choose: Advanced
# Choose: Single endpoint (typical for on-prem deployments)
# Enter your host and port
```

Once created, verify with `ax profiles show --all`:

```txt theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles show --all

Profile: my-onprem ● active

Authentication
  API Key: test-...key

Output
  Format: table

Routing
  Single Host: arize.yourcompany.com
  Single Port: 1234

Transport
  Stream Max Workers: 8
  Stream Max Queue Bound: 5000
  PyArrow Max Chunksize: 10000
  Max HTTP Payload Size: 8 MB

Security
  Request Verify: True

Storage
  Directory: ~/.arize
  Cache: True
```

### From file setup

You can also create a profile from a TOML file for repeatable or scripted setup:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ax profiles create my-onprem --from-file ./my-onprem.toml
```

### Routing strategies

#### Single endpoint (`single_host` / `single_port`)

The most common on-prem configuration. All Arize services (App, API, OTLP, Flight) are reachable through one host and port:

```toml theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
[routing]
single_host = "arize-app.internal.company.com"
single_port = "443"
```

#### Private Connect (`base_domain`)

For Private Connect setups where all services share a common base domain. The CLI generates `api.<base_domain>`, `otlp.<base_domain>`, and `flight.<base_domain>`:

```toml theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
[routing]
base_domain = "private.yourcompany.com"
```

#### Per-endpoint

When API, OTLP, and Flight each have separate hosts (four-endpoint deployment):

```toml theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
[routing]
api_host = "arize-api.internal.company.com"
api_scheme = "https"
otlp_host = "arize-otlp.internal.company.com"
otlp_scheme = "https"
flight_host = "arize-flight.internal.company.com"
flight_port = "443"
flight_scheme = "grpc+tls"
```

### TOML field reference

| Section | Field | Description |
| - | - | - |
| `[auth]` | `api_key` | Your Arize API key |
| `[routing]` | `single_host` | Single host for all endpoints (overrides per-endpoint fields) |
| `[routing]` | `single_port` | Port for single-host mode — required when `single_host` is set |
| `[routing]` | `base_domain` | Base domain for Private Connect (generates `api.*`, `otlp.*`, `flight.*`) |
| `[routing]` | `api_host` | Host for the Arize REST API (fallback when no override is set) |
| `[routing]` | `api_scheme` | `https` or `http` |
| `[routing]` | `otlp_host` | Host for OpenTelemetry trace ingestion |
| `[routing]` | `otlp_scheme` | `https` or `http` |
| `[routing]` | `flight_host` | Host for Arrow Flight (data export, datasets, experiments) |
| `[routing]` | `flight_port` | Port for Flight (typically `443`) |
| `[routing]` | `flight_scheme` | `grpc+tls` (TLS) or `grpc` (plaintext) |
| `[security]` | `request_verify` | `true` to verify TLS certificates, `false` to skip (dev only) |
| `[output]` | `format` | Default output format: `table`, `json`, `csv`, `parquet` |

### TLS and enterprise certificates

Set `request_verify = false` under `[security]` to bypass certificate verification during development with self-signed certificates. For production, keep it `true` and if you're using a custom CA, configure it at the OS or environment level . See [Using an Enterprise-Issued Certificate](/docs/ax/selfhosting/on-premise-sdk-usage/version-8#using-an-enterprise-issued-certificate) for details on certificate configuration.