arize-projects

Arize AX Projects

Manage projects in the Arize AI platform using the ax CLI.

Prerequisites

The user must have:

1. Arize AX CLI installed (pip install arize-ax-cli)
2. CLI configured with valid credentials (ax config init)

Core Project Commands

List Projects

ax projects list

Options:

• --space-id <id> - Space ID to list projects from (uses config default if not set)
• --limit, -n <count> - Maximum number of projects to return (default: 15)
• --cursor <token> - Pagination cursor for next page
• --output, -o <format> - Output format: table (default), json, csv, parquet, or a file path
• --profile, -p <name> - Configuration profile to use
• --verbose, -v - Enable verbose logs

Examples:

# List projects (default table format)
ax projects list

# List as JSON
ax projects list --output json

# List from a specific space
ax projects list --space-id sp_abc123

# Limit results
ax projects list -n 5

# Use production profile
ax projects list --profile production

Extracting Project IDs:

# Get all project IDs and names as JSON
ax projects list --output json | jq '.[] | {id: .id, name: .name}'

# Find a project ID by name
ax projects list --output json | jq -r '.[] | select(.name == "My Project") | .id'

# Save project ID to a variable
PROJECT_ID=$(ax projects list --output json | jq -r '.[] | select(.name == "My Project") | .id')
echo "Found project: $PROJECT_ID"

Without jq (using grep):

# Find project by name
ax projects list --output json | grep -B 1 '"name": "My Project"' | grep "id" | cut -d'"' -f4

Resolving Project Names to IDs

The CLI commands (get, delete) require a project ID, not a name. When a user refers to a project by name, resolve the ID first using projects list:

1. Run ax projects list --output json
2. Parse the JSON to find the project matching the requested name
3. Use the resolved ID for subsequent commands

If no exact match is found, check for partial or case-insensitive matches and confirm with the user before proceeding. If multiple matches exist, present the options and ask the user to choose.

# Example: user asks to "get the ML Experiments project"
PROJECT_ID=$(ax projects list --output json | jq -r '.[] | select(.name == "ML Experiments") | .id')
if [ -z "$PROJECT_ID" ]; then
  echo "Project not found. Available projects:"
  ax projects list --output json | jq '.[] | {id: .id, name: .name}'
else
  ax projects get "$PROJECT_ID"
fi

Get Project Details

Retrieve information about a specific project:

ax projects get <project-id>

Arguments:

• id (required) - The project ID

Options:

• --output, -o <format> - Output format: table (default), json, csv, parquet, or a file path
• --profile, -p <name> - Configuration profile to use
• --verbose, -v - Enable verbose logs

Examples:

# Get project details
ax projects get proj_abc123

# Get as JSON
ax projects get proj_abc123 --output json

# Get from production environment
ax projects get proj_abc123 --profile production

Create a Project

Create a new project in a space:

ax projects create --name <name> --space-id <space-id>

Options:

• --name, -n <name> (required) - Project name (prompted interactively if not provided)
• --space-id <id> (required) - Space ID to create the project in (prompted interactively if not provided)
• --output, -o <format> - Output format: table (default), json, csv, parquet, or a file path
• --profile, -p <name> - Configuration profile to use
• --verbose, -v - Enable verbose logs

Examples:

# Create with all options specified
ax projects create --name "ML Experiments" --space-id sp_abc123

# Create interactively (prompts for name and space-id)
ax projects create

# Create and output as JSON
ax projects create --name "Staging Tests" --space-id sp_abc123 --output json

# Create using a specific profile
ax projects create --name "Production Project" --space-id sp_abc123 --profile production

Delete a Project

Remove a project by ID:

ax projects delete <project-id>

Arguments:

• id (required) - The project ID

Options:

• --force, -f - Skip confirmation prompt
• --profile, -p <name> - Configuration profile to use
• --verbose, -v - Enable verbose logs

Examples:

# Delete with confirmation prompt
ax projects delete proj_abc123

# Delete without confirmation
ax projects delete proj_abc123 --force

# Delete from production
ax projects delete proj_abc123 --profile production

Warning: Deletion is permanent. Always verify the project ID before deleting.

Pagination

The projects list command uses cursor-based pagination. The response includes a cursor for fetching the next page:

# First page
ax projects list -n 10 --output json

# Use the cursor from the previous response to get the next page
ax projects list -n 10 --cursor <cursor-from-previous-response>

Common Workflows

Workflow 1: Find Project by Name and Get Details

# 1. List all projects
ax projects list --output json | jq '.[] | {id: .id, name: .name}'

# 2. Extract the project ID by name
PROJECT_ID=$(ax projects list --output json | jq -r '.[] | select(.name == "ML Experiments") | .id')

# 3. Get detailed information
ax projects get "$PROJECT_ID"

Workflow 2: Create and Verify a Project

# 1. Create the project
ax projects create --name "New Experiment" --space-id sp_abc123

# 2. Find the new project ID
PROJECT_ID=$(ax projects list --output json | jq -r '.[] | select(.name == "New Experiment") | .id')
echo "Created project: $PROJECT_ID"

# 3. Verify details
ax projects get "$PROJECT_ID"

Workflow 3: Work with Projects Across Environments

# List projects in production
ax projects list --profile production

# Create project in staging
ax projects create --name "Test Project" --space-id sp_staging_123 --profile staging

# Get project details from dev
ax projects get proj_dev_456 --profile dev

Workflow 4: Cleanup Old Projects

# 1. List all projects
ax projects list --output json | jq '.[] | {id: .id, name: .name}'

# 2. Review and identify projects to delete

# 3. Delete old projects
ax projects delete proj_old_001 --force
ax projects delete proj_old_002 --force

Output Format Examples

Table Format (Default)

Human-readable table with columns for ID, Name, Created, and other metadata.

JSON Format

Structured JSON with full project metadata:

{
  "id": "proj_abc123",
  "name": "ML Experiments",
  "space_id": "sp_xyz789",
  "created_at": "2024-01-15T10:30:00Z"
}

CSV / Parquet

Use --output csv or --output parquet for data-processing-friendly formats. You can also pass a file path to write directly to a file:

ax projects list --output projects.csv
ax projects list --output projects.parquet

Troubleshooting

"Project not found"

1. Verify project ID: ax projects list
2. Check you're using the correct profile: ax config show
3. Ensure the project exists in the current space

"Permission denied" or "Unauthorized"

1. Check API key is valid: ax config show --expand
2. Verify the key has project permissions in Arize
3. Try re-authenticating: ax config init

"Space not found" when creating

1. Verify the space ID is correct
2. Check your profile has the right space configured: ax config show
3. List available spaces or check https://app.arize.com

Cannot list projects

1. Check CLI is configured: ax config show
2. Verify network connectivity
3. Try with --verbose for more detail: ax projects list --verbose

Tips

1. Extract project IDs by name:

   PROJECT_ID=$(ax projects list --output json | jq -r '.[] | select(.name == "My Project") | .id')
   

2. Use JSON output for scripting: ax projects list --output json | jq '.[] | .id'
3. List IDs and names together: ax projects list --output json | jq '.[] | {id, name}'
4. Verify before delete: Use ax projects get "$PROJECT_ID" to confirm before deleting
5. Profile naming: Use descriptive names like prod, staging, dev
6. Use --force in scripts: Skip interactive confirmation with -f when automating

Next Steps

• View project details in Arize UI: https://app.arize.com
• Use /arize-datasets to manage datasets within projects
• Visit https://docs.arize.com for full documentation

When to Use This Skill

Use this skill when users want to:

• ✅ List all projects in their Arize space
• ✅ Get details about a specific project
• ✅ Create a new project
• ✅ Delete projects they no longer need
• ✅ Work with projects across multiple environments/profiles

Don't use this skill for:

• ❌ Managing datasets (use /arize-datasets instead)
• ❌ Installing/configuring the CLI (use /setup-arize-cli instead)