> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ansible/awx/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Installation

> Install and set up the AWX command-line interface

The AWX CLI (`awx`) is the official command-line interface for Ansible AWX, providing programmatic access to AWX resources through a simple and intuitive command structure.

## Overview

The `awxkit` package provides:

* **awx** - The main CLI tool for interacting with AWX/Ansible Automation Platform
* **akit** - An interactive Python session with awxkit loaded

The CLI is built on top of the `awxkit` Python library and provides HTTP OPTIONS-based resource discovery and action mapping.

## Requirements

* **Python**: 3.11 or higher (Python 3.11 and 3.12 are officially supported)
* **Operating System**: Linux or macOS
* **Network Access**: Connection to an AWX or Ansible Automation Platform instance

## Installation Methods

### Install from PyPI

The recommended way to install the AWX CLI is via pip:

```bash theme={null}
pip install awxkit
```

### Install from GitHub

To install a specific version matching your AWX deployment:

```bash theme={null}
pip install "git+https://github.com/ansible/awx.git@$VERSION#egg=awxkit&subdirectory=awxkit"
```

Replace `$VERSION` with your AWX version (e.g., `23.4.0`). To see all available releases, visit: [https://github.com/ansible/awx/releases](https://github.com/ansible/awx/releases)

### Install from Source

For development or customization:

```bash theme={null}
git clone https://github.com/ansible/awx.git
cd awx/awxkit
pip install -e .
```

## Core Dependencies

The following dependencies are automatically installed:

* **PyYAML** - YAML parsing support
* **requests** - HTTP client library
* **setuptools** - Python package utilities

## Optional Dependencies

### Output Formatting

For advanced JSON output filtering with jq:

```bash theme={null}
pip install awxkit[formatting]
```

<Note>
  The jq extra requires `libtool` and other build dependencies on some platforms. See [jq PyPI page](https://pypi.org/project/jq/) for platform-specific requirements.
</Note>

### WebSocket Support

For real-time job output monitoring via WebSockets:

```bash theme={null}
pip install awxkit[websockets]
```

### Cryptography

For additional cryptographic functionality:

```bash theme={null}
pip install awxkit[crypto]
```

### Install All Optional Features

```bash theme={null}
pip install awxkit[formatting,websockets,crypto]
```

## Verify Installation

After installation, verify the CLI is available:

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

This should display the installed version of awxkit.

## Platform-Specific Notes

### Linux

On most Linux distributions, you can install directly with pip. Some distributions may require:

```bash theme={null}
sudo apt-get install python3-pip  # Debian/Ubuntu
sudo yum install python3-pip      # RHEL/CentOS
```

### macOS

On macOS, use Homebrew's Python or the system Python:

```bash theme={null}
brew install python3
pip3 install awxkit
```

### Virtual Environments

It's recommended to use virtual environments to avoid conflicts:

```bash theme={null}
python3 -m venv awx-env
source awx-env/bin/activate  # On Windows: awx-env\Scripts\activate
pip install awxkit
```

## Ansible Automation Platform Considerations

When using AWX CLI with Red Hat Ansible Automation Platform 2.5 and later, you must set an environment variable:

```bash theme={null}
export AWXKIT_API_BASE_PATH=/api/controller/
```

Add this to your shell profile (`~/.bashrc`, `~/.zshrc`) to make it persistent:

```bash theme={null}
echo 'export AWXKIT_API_BASE_PATH=/api/controller/' >> ~/.bashrc
```

## Upgrade AWX CLI

To upgrade to the latest version:

```bash theme={null}
pip install --upgrade awxkit
```

To upgrade to a specific version:

```bash theme={null}
pip install awxkit==23.4.0
```

## Uninstall

To remove the AWX CLI:

```bash theme={null}
pip uninstall awxkit
```

## Next Steps

After installation, proceed to:

* [Configuration](/cli/configuration) - Set up authentication and connection settings
* [Usage](/cli/usage) - Learn basic CLI commands and patterns
* [Commands](/cli/commands) - Explore available resources and actions


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.