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

# AX CLI

> Command-line interface for managing Arize AX resources

The AX CLI (`ax`) lets you manage your Arize AI platform resources — datasets, projects, spans, and configuration profiles — directly from your terminal. It's useful for scripting workflows, automating data pipelines, and integrating Arize into CI/CD environments.

## Getting Started

### 1. Install the CLI

<Info>
  Requires Python 3.11 or later.
</Info>

```bash theme={null}
pip install arize-ax-cli
```

Verify the installation:

```bash theme={null}
ax --version
```

### 2. Create a configuration profile

```bash theme={null}
ax profiles create
```

You'll be prompted for your API key, region, and preferred output format. Choose **Simple mode** for most use cases, or **Advanced mode** for custom routing, transport tuning, and SSL settings.

<Warning>
  `ax profiles create` is required before running any other commands. Without it, most commands will fail with: `Error: Profile 'default' not found.`
</Warning>

### 3. Verify your setup

```bash theme={null}
ax profiles show    # Check your profile settings
ax projects list    # Run your first command
```

### Shell Completion (optional)

Enable tab completion for your shell:

```bash theme={null}
ax --install-completion
```

Supports bash, zsh, fish, and PowerShell. Restart your shell or source your profile to activate.

***

## Configuration

Profiles store your API key, region, and output preferences so you don't have to pass them on every command.

Configuration files are stored at:

* **macOS/Linux:** `~/.arize/profiles/<profile>.toml`
* **Windows:** `%USERPROFILE%\.arize\profiles\<profile>.toml`

The CLI automatically detects any `ARIZE_*` environment variables in your shell and offers to use them during `ax profiles create`. You can also reference environment variables in config files using `${VARIABLE_NAME}` syntax.

<Info>
  **Using a self-hosted, on-premise, or VPC deployment?** You'll need to configure custom endpoint routing in your profile. See [Self-Hosted / On-Premise Configuration](/api-clients/cli/profiles#self-hosted--on-premise-configuration) for setup instructions.
</Info>

### Managing Profiles

Here's a full reference of profile commands:

```bash theme={null}
ax profiles create                       # Create a new profile
ax profiles list                         # List all profiles (active profile is marked)
ax profiles show                         # Show active profile settings
ax profiles show myprofile               # Show a specific profile
ax profiles show --expand                # Resolve environment variable references
ax profiles show --all                   # Show all sections including defaults
ax profiles use <profile>                # Switch the active profile
ax profiles delete <profile>             # Delete a profile (cannot delete default or active)
ax profiles delete <profile> --force     # Delete without confirmation prompt
```

### Working with Multiple Environments

Create separate profiles for production and staging, then switch between them as needed:

```bash theme={null}
ax profiles create   # name it "production"
ax profiles create   # name it "staging"

# Switch the active profile
ax profiles use production

# Or override per-command with --profile
ax datasets list --profile staging --space sp_stg123
```

***

## Options & Output

### Top-Level Options

These options are available on the root `ax` command itself:

| Option                 | Short | Description                           |
| ---------------------- | ----- | ------------------------------------- |
| `--version`            |       | Show version and exit                 |
| `--install-completion` |       | Install shell completion              |
| `--show-completion`    |       | Show completion script for your shell |
| `--help`               | `-h`  | Show help                             |

### Subcommand Options

Most subcommands (e.g., `ax datasets list`, `ax projects get`) accept these options:

| Option                    | Short | Description                                                                   |
| ------------------------- | ----- | ----------------------------------------------------------------------------- |
| `--profile <name>`        | `-p`  | Use a specific configuration profile instead of the active one                |
| `--output <format\|path>` | `-o`  | Set output format (`table`, `json`, `csv`, `parquet`) or write to a file path |
| `--verbose`               | `-v`  | Enable detailed logging                                                       |
| `--help`                  | `-h`  | Show help for the command                                                     |

<Note>
  `--profile` and `--output` are subcommand options, not top-level flags. Use them after the subcommand: `ax datasets list --profile staging`, not `ax --profile staging datasets list`.
</Note>

### Output Formats

The default output format is `table`. Use `--output` to change the format or write results directly to a file:

| Format    | Description                                        |
| --------- | -------------------------------------------------- |
| `table`   | Human-readable default; formatted for the terminal |
| `json`    | Machine-parseable JSON                             |
| `csv`     | Spreadsheet-compatible format                      |
| `parquet` | Apache columnar format for large datasets          |

```bash theme={null}
ax datasets list --output json                                 # Print as JSON
ax datasets list --output datasets.json                        # Write to a JSON file
ax datasets export <dataset-id> --stdout | jq '.' > out.json   # Pipe export to file
```

***

## Cache

The CLI caches certain data locally at `~/.arize/cache/` to speed up repeated operations. To clear the cache:

```bash theme={null}
ax cache clear
```

***

## Resources

<CardGroup cols={4}>
  <Card title="AI Integrations" href="/api-clients/cli/ai-integrations" icon="plug">
    Create and manage LLM provider integrations
  </Card>

  <Card title="Annotation Configs" href="/api-clients/cli/annotation-configs" icon="tag">
    Create and manage annotation schemas
  </Card>

  <Card title="API Keys" href="/api-clients/cli/api-keys" icon="key">
    Create, refresh, and revoke API keys
  </Card>

  <Card title="Datasets" href="/api-clients/cli/datasets" icon="database">
    Create, list, and manage datasets
  </Card>

  <Card title="Evaluators" href="/api-clients/cli/evaluators" icon="scale-balanced">
    Create and manage LLM-as-judge evaluators
  </Card>

  <Card title="Experiments" href="/api-clients/cli/experiments" icon="flask">
    Create, list, and manage experiments
  </Card>

  <Card title="Projects" href="/api-clients/cli/projects" icon="folder">
    Create, list, and manage projects
  </Card>

  <Card title="Prompts" href="/api-clients/cli/prompts" icon="message">
    Create and version prompt templates
  </Card>

  <Card title="Spaces" href="/api-clients/cli/spaces" icon="building">
    Create, list, and manage spaces
  </Card>

  <Card title="Spans" href="/api-clients/cli/spans" icon="chart-gantt">
    Export span data with filtering
  </Card>

  <Card title="Tasks" href="/api-clients/cli/tasks" icon="circle-check">
    Create and manage evaluation tasks
  </Card>

  <Card title="Traces" href="/api-clients/cli/traces" icon="arrow-progress">
    List and export trace data
  </Card>

  <Card title="Users" href="/api-clients/cli/users" icon="user">
    Create, list, and manage users
  </Card>
</CardGroup>

***

## Useful Links

<CardGroup cols={2}>
  <Card title="PyPI Package" href="https://pypi.org/project/arize-ax-cli/" icon="python">
    Install and version history
  </Card>

  <Card title="GitHub Repository" href="https://github.com/Arize-ai/arize-ax-cli" icon="github">
    Source code and issues
  </Card>

  <Card title="Arize Community Slack" href="https://arize-ai.slack.com" icon="slack">
    Get help from the community
  </Card>

  <Card title="Support" href="mailto:support@arize.com" icon="envelope">
    Contact the Arize support team
  </Card>
</CardGroup>