arize-ax-cli 0.0.0

Official Arize CLI tool for managing datasets, experiments, and more

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)

Installation

pip install arize-ax-cli

Quick Start

1. Initialize Configuration

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

ax datasets list

3. Create a Dataset

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

4. View Help

ax --help
ax datasets --help
ax config --help

Commands

Global Options

Available on all commands:

--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:

-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:

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

Precedence: command flag > environment variable > config file

Configuration Management

# 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

# 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

# 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

[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

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

# 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:

# 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)

### 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

#!/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

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

Zsh

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

Fish

ax --install-completion fish

Development

Setup Development Environment

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

pytest
pytest --cov=ax --cov-report=html

Code Quality

# 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:

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

Configuration Issues

To reset configuration:

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.