Installation

Instructions for installing StackQL on various different platforms are provided here.

macOS

macOS

StackQL is available on macOS via Homebrew and the pkg Installer, both ARM (M1/Apple Silicon) and AMD architectures are supported with a single multi-arch installer.

Homebrew

To install via Homebrew, run the following command in your terminal:

brew install stackql

Package download

StackQL is available as a signed and notarized, interactive pkg installer for MacOS.

Download macOS PKG  

Linux

Linux

StackQL is available for all Linux architectures.

using curl

amd64

curl -L https://bit.ly/stackql-zip -O \
&& unzip stackql-zip

arm64

curl -L https://bit.ly/stackql-arm64 -O \
&& unzip stackql-arm64

Package download

Alternatively, you can download the binaries here:

Download Linux ZIP (amd64)  

Download Linux ZIP (arm64)  

Windows

Windows

StackQL is available on Windows via Chocolatey and the msi Installer, x64 and x86 architectures are supported.

Chocolatey

To install via Chocolatey, run the following command in your PowerShell or cmd terminal:

choco install stackql

Package download

Alternatively, the Windows stackql binary can be downloaded here.

Download Windows MSI  

Download Windows ZIP  

Docker

Docker

StackQL builds are published to DockerHub.

Docker Hub

To pull the StackQL container image, run the following command:

docker pull stackql/stackql

stackql-deploy

stackql-deploy

StackQL Deploy is a Python package that enables infrastructure deployment using StackQL. It provides a simplified interface for managing cloud resources across multiple providers with SQL-like syntax. For more detailed information see StackQL Deploy Docs.

PyPi

The package is available on PyPI and can be installed using pip.

Direct Install

pip install stackql-deploy

Virtual Environment

python -m venv stackql-env
source stackql-env/bin/activate  # On Windows, use: stackql-env\Scripts\activate
pip install stackql-deploy

Cloud Shells

Cloud Shells

StackQL can be used directly from major cloud providers' built-in cloud shells. This provides a seamless experience as these cloud shells are pre-authorized with your credentials for the cloud provider account you're logged into, eliminating the need for separate authentication setup.

AWS

AWS Cloud Shell

AWS CloudShell provides a browser-based shell with AWS CLI pre-installed and authenticated. Running StackQL in AWS CloudShell allows you to query and manage AWS resources without additional authentication steps. For detailed instructions, see our AWS CloudShell tutorial.

First, download the StackQL package:

curl -L https://bit.ly/stackql-zip -O \
&& unzip stackql-zip

Then run the StackQL AWS CloudShell script:

sh stackql-aws-cloud-shell.sh

This script starts a StackQL command shell using your AWS CloudShell credentials, allowing you to immediately start querying AWS resources.

Azure

Azure Cloud Shell

Azure Cloud Shell provides a browser-accessible shell environment with Azure CLI pre-authenticated with your Azure account. Using StackQL in Azure Cloud Shell enables seamless querying of your Azure resources without additional setup. For complete details, check our Azure Cloud Shell guide.

First, download the StackQL package:

curl -L https://bit.ly/stackql-zip -O \
&& unzip stackql-zip

Then run the StackQL Azure Cloud Shell script:

sh stackql-azure-cloud-shell.sh

This script automatically configures a StackQL session to use your Azure Cloud Shell credentials, enabling immediate access to query your Azure resources.

Google

Google Cloud Shell

Google Cloud Shell offers a development and operations environment with Google Cloud CLI already authenticated. Running StackQL in Google Cloud Shell lets you query GCP resources using your existing authentication. Learn more in our Google Cloud Shell guide.

First, download the StackQL package:

curl -L https://bit.ly/stackql-zip -O \
&& unzip stackql-zip

Then run the StackQL Google Cloud Shell script:

sh stackql-google-cloud-shell.sh

The script sets up StackQL to use your Google Cloud Shell credentials, allowing you to immediately start querying your GCP resources using SQL syntax.

Using GitHub Actions

StackQL GitHub Actions are available for use in your GitHub Actions workflows. The following actions are available:

stackql-deploy

stackql-deploy

Deploy or test infrastructure stacks using StackQL directly from your GitHub workflows. This action enables Infrastructure as Code (IaC) workflows using SQL-like syntax, allowing you to define, deploy, and manage cloud resources across multiple providers in a single workflow.

View on the GitHub Marketplace  

Example usage

...
jobs:
  stackql-actions-test:
    name: StackQL Actions Test
    runs-on: ubuntu-latest
    env:
      GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }} # add additional cloud provider creds here as needed
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy a Stack
        uses: stackql/stackql-deploy-action@v1.0.2
        with:
          command: 'build'
          stack_dir: 'examples/k8s-the-hard-way'
          stack_env: 'dev'
          env_vars: 'GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo'

setup-stackql

setup-stackql

Setup StackQL in your GitHub Actions workflow.

View on the GitHub Marketplace  

Example usage

- name: setup StackQL
  uses: stackql/setup-stackql@v2.2.3
  with:
    use_wrapper: true

- name: Use GitHub Provider
  run: |
    stackql exec -i ./examples/github-example.iql
  env: 
    STACKQL_GITHUB_USERNAME: ${{  secrets.STACKQL_GITHUB_USERNAME }}
    STACKQL_GITHUB_PASSWORD: ${{  secrets.STACKQL_GITHUB_PASSWORD }}

stackql-exec

stackql-exec

Execute StackQL commands in your GitHub Actions workflow. Queries can be supplied in line or from a file in the repo.

View on the GitHub Marketplace  

Example usage

- name: exec github example
  uses: stackql/stackql-exec@v2.2.3
  with:
    query: |
      select total_private_repos
      from github.orgs.orgs
      where org = 'stackql'"
  env: 
    STACKQL_GITHUB_USERNAME: ${{  secrets.STACKQL_GITHUB_USERNAME }}
    STACKQL_GITHUB_PASSWORD: ${{  secrets.STACKQL_GITHUB_PASSWORD }}

stackql-assert

stackql-assert

Perform unit tests in your GitHub Actions workflow (for assurance, governance or cloud security checks).

View on the GitHub Marketplace  

Example usage

- name: Use test query string and expected rows
  uses: stackql/stackql-assert@v2.2.3
  with:
    test_query: |
        SELECT name
        FROM google.compute.instances 
        WHERE project = 'stackql-demo' AND zone = 'australia-southeast1-a' AND name = 'stackql-demo-001';
    expected_rows: 1
  env: 
    GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }}

Other Libraries

StackQL provides several integration methods that allow you for use in different programming languages and environments. These libraries extend StackQL's functionality, making it easy to incorporate cloud resource querying and management into your existing applications and workflows.

pystackql

pystackql Python Package

Python wrapper to use StackQL in your Python programs. The pystackql package is available on PyPi, documentation for the pystackql package is available via Read the Docs. To install the pystackql package, run the following command:

pip install pystackql

The following example shows the pystackql package used along with pandas to run StackQL queries and return the results to a pandas.DataFrame:

from pystackql import StackQL
import pandas as pd
region = "ap-southeast-2"
stackql = StackQL()

query = """
SELECT instance_type, COUNT(*) as num_instances
FROM aws.ec2.instances
WHERE region = '%s'
GROUP BY instance_type
""" % (region)

res = stackql.execute(query)
df = pd.read_json(res)
print(df)