arize-ax 0.1.0
Official Arize CLI tool for managing datasets, experiments, and more
License: Apache-2.0
Requires Python: >=3.12
Keywords: arize, cli, llm, machine-learning, mlops, observability

# Arize CLI (`ax`)

Official command-line interface for Arize AI. Manage datasets, experiments, and more from your terminal.

## Features

- **Dataset Management**: Create, list, and manage datasets with support for CSV, JSON, JSONL, and Parquet formats
- **Experiment Management**: Run and track experiments with your datasets
- **Profile Management**: Multiple configuration profiles for different environments (dev, staging, prod)
- **Rich Output**: Beautiful table formatting, JSON, CSV, and Parquet export options
- **Interactive**: Confirmation prompts, progress bars, and helpful error messages
- **Type-Safe**: Built with modern Python 3.12+ and Typer for excellent IDE support

## Requirements

- Python 3.12 or higher
- Arize API key ([get one here](https://app.arize.com/settings/api-keys))

## Installation

```bash
pip install arize-ax
```

Or install from source:

```bash
git clone https://github.com/Arize-ai/client_python.git
cd client_python/ax-cli
pip install -e .
```

## Quick Start

### 1. Initialize Configuration

```bash
ax config init
```

This will interactively prompt you for:
- API Key
- Default Space ID (optional)
- Region (us-central-1a, eu-west-1a, ca-central-1a, us-east-1b)
- Output preferences

### 2. List Datasets

```bash
ax datasets list
```

### 3. Create a Dataset

```bash
ax datasets create --name "My Dataset" --file data.csv
```

### 4. View Help

```bash
ax --help
ax datasets --help
ax config --help
```

## Commands

### Global Options

Available on all commands:

```bash
--api-key TEXT         Override API key
--region TEXT          Override region
--profile TEXT         Use specific profile
--no-color            Disable colored output
--verbose, -v         Verbose output
--quiet, -q           Suppress non-essential output
--help, -h            Show help
--version             Show version
```

### Command-Level Options

These options are available on specific commands and are passed after the subcommand:

#### Output Option

Available on list and export commands:

```bash
-o, --output TEXT      Output format (table, json, csv, parquet) or file path
```

The `-o` option intelligently handles both formats and file paths:
- Format names (`table`, `json`, `csv`, `parquet`) output to stdout
- File paths (`data.json`, `output.csv`) save to file with auto-detected format

#### Space ID Option

Available on dataset commands:

```bash
--space-id TEXT        Space ID (env: ARIZE_SPACE_ID, config: defaults.space_id)
```

Precedence: command flag > environment variable > config file

### Configuration Management

```bash
# Initialize configuration
ax config init
ax config init --profile dev

# Show configuration
ax config show
ax config show --profile prod

# Set a value
ax config set auth.api_key "new-key"
ax config set defaults.region eu-west-1a

# Get a value
ax config get auth.api_key

# Clear cache
ax config clear-cache

# Profile management
ax config profile list
ax config profile use dev
ax config profile show
ax config profile delete old-profile
```

### Dataset Commands

```bash
# List datasets
ax datasets list
ax datasets list --limit 100
ax datasets list --space-id my-space --limit 100

# List with different output formats (to stdout)
ax datasets list -o json
ax datasets list -o csv
ax datasets list -o table

# Save to file (format auto-detected from extension)
ax datasets list -o datasets.json
ax datasets list -o datasets.csv
ax datasets list -o datasets.parquet

# Combine options naturally
ax datasets list --space-id my-space -o json
ax datasets list --space-id my-space -o datasets.csv

# Create dataset from file
ax datasets create --name "Training Data" --file data.csv
ax datasets create --name "Test Data" --file data.json --space-id my-space

# Get dataset details
ax datasets get --id dataset-123

# Delete dataset (with confirmation)
ax datasets delete --id dataset-123
ax datasets delete --id dataset-123 --force

# List dataset examples
ax datasets examples --id dataset-123 --limit 500
ax datasets examples --id dataset-123 -o json
ax datasets examples --id dataset-123 -o examples.csv
```

### Experiment Commands

```bash
# List experiments
ax experiments list
ax experiments list --dataset-id dataset-123

# List with different output formats
ax experiments list -o json
ax experiments list -o experiments.csv

# Create experiment
ax experiments create --name "Experiment 1" --dataset-id dataset-123

# Get experiment details
ax experiments get --id exp-123

# Delete experiment
ax experiments delete --id exp-123

# Run experiment (coming soon)
ax experiments run --id exp-123 --task task.py
ax experiments run --id exp-123 --task task.py --async

# List experiment runs (coming soon)
ax experiments runs --id exp-123
```

## Configuration

### Configuration File Locations

- Default profile: `~/.arize/config.toml`
- Named profiles: `~/.arize/profiles/<profile-name>.toml`
- Active profile marker: `~/.arize/.active_profile`

### Configuration Structure

```toml
[profile]
name = "default"

[auth]
api_key = "your-api-key"

[defaults]
space_id = "default-space-id"
region = "us-central-1a"

[output]
format = "table"
color = true

[cache]
enabled = true
directory = "~/.arize/cache"
```

### Configuration Precedence

Settings are resolved in this order (highest to lowest):

1. Command-line flags (`--api-key`, `--region`, etc.)
2. Environment variables (`ARIZE_API_KEY`, `ARIZE_REGION`, `ARIZE_PROFILE`)
3. Active profile config file
4. Default profile config file
5. SDK defaults

### Environment Variables

```bash
export ARIZE_API_KEY="your-api-key"
export ARIZE_REGION="us-central-1a"
export ARIZE_SPACE_ID="your-space-id"
export ARIZE_PROFILE="dev"
```

## Examples

### Working with Multiple Profiles

```bash
# Create profiles for different environments
ax config init --profile dev
ax config init --profile staging
ax config init --profile prod

# Switch between profiles
ax config profile use staging

# Or use --profile flag
ax datasets list --profile prod

# Or use environment variable
export ARIZE_PROFILE=dev
ax datasets list
```

### Output Options

The `-o` / `--output` option accepts either a format name or a file path:

```bash
# Output format to stdout
ax datasets list -o json        # JSON to stdout
ax datasets list -o csv         # CSV to stdout
ax datasets list -o table       # Pretty table to stdout (default)
ax datasets list -o parquet     # Parquet to stdout (binary)

# Save to file (format auto-detected from extension)
ax datasets list -o datasets.json     # JSON file
ax datasets list -o datasets.csv      # CSV file
ax datasets list -o datasets.parquet  # Parquet file

# Examples with dataset examples
ax datasets examples --id dataset-123 -o json
ax datasets examples --id dataset-123 -o examples.csv
ax datasets examples --id dataset-123 -o examples.parquet

# Output format can also be set in config profile
ax --profile json datasets list  # Uses json format from profile
```

The output option respects this precedence:
1. `-o` / `--output` flag (highest priority)
2. Config file `output.format` setting
3. Default (`table`)

```bash

### Creating Datasets from Different Formats

```bash
# From CSV
ax datasets create --name "CSV Data" --file data.csv

# From JSON
ax datasets create --name "JSON Data" --file data.json

# From JSON Lines
ax datasets create --name "JSONL Data" --file data.jsonl

# From Parquet
ax datasets create --name "Parquet Data" --file data.parquet
```

### Scripting and Automation

```bash
#!/bin/bash

# Set environment variables
export ARIZE_API_KEY="your-key"
export ARIZE_SPACE_ID="your-space"

# Create dataset
DATASET_ID=$(ax datasets create --name "Auto Dataset" --file data.csv -o json | jq -r '.id')

# Create experiment
EXP_ID=$(ax experiments create --name "Auto Exp" --dataset-id "$DATASET_ID" -o json | jq -r '.id')

echo "Created experiment $EXP_ID for dataset $DATASET_ID"
```

## Shell Completion

Typer provides automatic shell completion. To install:

### Bash

```bash
ax --install-completion bash
source ~/.bashrc
```

### Zsh

```bash
ax --install-completion zsh
source ~/.zshrc
```

### Fish

```bash
ax --install-completion fish
```

## Development

### Setup Development Environment

```bash
git clone https://github.com/Arize-ai/client_python.git
cd client_python/ax-cli

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
pytest --cov=ax --cov-report=html
```

### Code Quality

```bash
# Format and lint
ruff check src/
ruff format src/

# Type checking
mypy src/
```

## Troubleshooting

### Authentication Errors

If you see "API key not found" or authentication errors:

1. Verify your API key is correct
2. Check configuration: `ax config show`
3. Try re-initializing: `ax config init --force`
4. Verify key at: https://app.arize.com/settings/api-keys

### Import Errors

If you get import errors after installation:

```bash
pip install --upgrade arize-ax
# Or if installed from source:
pip install -e . --force-reinstall
```

### Configuration Issues

To reset configuration:

```bash
rm -rf ~/.arize
ax config init
```

## Support

- Documentation: https://docs.arize.com/cli
- GitHub Issues: https://github.com/Arize-ai/client_python/issues
- Community: https://arize.com/community

## License

Apache License 2.0 - see LICENSE file for details.

## Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.