# Installation

> Install StackQL on macOS, Linux, Windows, Docker or a cloud shell, and use the StackQL MCP server from Claude Desktop, ChatGPT, Goose and other MCP clients, or via npx, uvx, pip, Docker and GitHub Actions.

Source: https://stackql.io/installing-stackql

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:

```bash
brew install stackql
```

**curl (signed and notarized binary)**

To install a signed and notarized `stackql` executable binary in the current directory, run the following command in your terminal:

```bash
curl -fsSL https://get-stackql.io/install | sh
```

**Package download**

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

[Download macOS PKG](https://releases.stackql.io/stackql/latest/stackql_darwin_multiarch.pkg)

**Linux**

## Linux

StackQL is available for all Linux architectures.

**curl**

To install a `stackql` executable binary in the current directory for your linux architecture (amd64 or arm64), run the following command in your terminal:

```bash
curl -fsSL https://get-stackql.io/install | sh
```

**Package download**

Alternatively, you can download the binaries here:

[Download Linux ZIP (amd64)](https://releases.stackql.io/stackql/latest/stackql_linux_amd64.zip)
[Download Linux ZIP (arm64)](https://releases.stackql.io/stackql/latest/stackql_linux_arm64.zip)

**Windows**

## Windows

StackQL is available on Windows via Chocolatey, PowerShell install script, and the MSI installer. The x64 (AMD64) build is supported and also runs on ARM64 via emulation. All executables are signed with an Authenticode code-signing certificate.

**Chocolatey**

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

```powershell
choco install stackql
```

**Invoke-RestMethod**

To install an Authenticode executable in the current directory, run the following in a Powershell terminal: 

```powershell
Invoke-RestMethod https://get-stackql.io/install | Invoke-Expression
# or
irm https://get-stackql.io/install | iex
```

**MSI/ZIP download**

Alternatively, the signed Windows `stackql` installer package or executable can be downloaded here.

[Download Windows MSI](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.msi)
[Download Windows ZIP](https://releases.stackql.io/stackql/latest/stackql_windows_amd64.zip)

**Docker**

## Docker

StackQL builds are published to [DockerHub](https://hub.docker.com/u/stackql).  

__Docker Hub__  

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

```bash
docker pull stackql/stackql
```

**stackql-deploy**

## `stackql-deploy`

`stackql-deploy` is a stateless IaC framework built on StackQL. For full documentation see [__StackQL Deploy Docs__](https://stackql-deploy.io/).

__Linux / macOS__

Downloads and extracts the latest `stackql-deploy` binary in one step. The installer detects your OS and architecture (including Apple Silicon and Intel via a universal macOS binary) and fetches the correct release asset automatically.
```bash
curl -fsSL https://get-stackql-deploy.io/install.sh | sh
```

__Windows__

Downloads and extracts the latest `stackql-deploy` binary into the current directory.
The installer detects your platform and fetches the correct release asset automatically.
```powershell
irm https://get-stackql-deploy.io/install.ps1 | iex
```

__cargo__

If you have the Rust toolchain installed, this builds and installs the binary directly from [__crates.io__](https://crates.io/crates/stackql-deploy).
```bash
cargo install stackql-deploy
```

**Cloud Shells**

## Cloud Shells

StackQL can be used directly from major cloud and data platforms' built-in cloud shells and web terminals. This provides a seamless experience as these environments are pre-authorized with the identity 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](/quick-starts/aws/aws-cloud-shell).

First, download the StackQL package:

```bash
curl -fsSL https://get-stackql.io/install/aws | sh
```
Then run the StackQL AWS CloudShell script:

```bash
./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](/blog/tutorials/using-stackql-in-native-cloud-shells-in-aws-azure-and-gcp#using-stackql-in-the-azure-cloud-shell).  

First, download the StackQL package:

```bash
curl -fsSL https://get-stackql.io/install/azure | sh
```

Then run the StackQL Azure Cloud Shell script:

```bash
./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](/blog/tutorials/using-stackql-in-native-cloud-shells-in-aws-azure-and-gcp#using-stackql-in-the-google-cloud-shell).  

First, download the StackQL package:

```bash
curl -fsSL https://get-stackql.io/install/google | sh
```

Then run the StackQL Google Cloud Shell script:

```bash
./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.

**Databricks**

### Databricks Web Terminal

Databricks workspaces include a web terminal that runs as the logged-in user. Running StackQL there lets you query your workspace using your Databricks identity, with no separate authentication setup. For example queries and account-level auth, see our [Databricks Web Terminal guide](/blog/tutorials/stackql-in-databricks-web-terminal).

First, download the StackQL package:

```bash
curl -fsSL https://get-stackql.io/install/databricks | sh
```

Then run the StackQL Databricks shell script:

```bash
./stackql-databricks-shell.sh
```

This starts a StackQL session using your Databricks workspace identity, so you can immediately query workspace-scoped resources such as `databricks_workspace.iam.vw_user_entitlements`. For account-level queries (provisioning, billing, account IAM), set the Databricks OAuth2 service principal variables as described in the guide.

## Using with MCP clients

The StackQL MCP server runs locally over stdio, so provider credentials stay on your machine whichever client you use. Pick your client below: each tab gives the directory or one-click route first and the manual configuration as a fallback. For every distribution channel, including `npx`, Python, Docker and CI, see [Installing the MCP server](#installing-the-mcp-server).

**Claude Desktop**

### Claude Desktop

  The recommended way to install the StackQL MCP server into Claude Desktop is from the [Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) (**Settings -> Connectors -> Add -> Browse Connectors**, search for **StackQL**) - Claude Desktop selects the correct signed binary for your platform automatically.  Alternatively, prebuilt MCP Bundles (`.mcpb`) are attached to every StackQL release for installation from a downloaded file - no separate StackQL installation is required either way.  Bundles are available for macOS, Windows and Linux.

  [Download macOS MCPB](https://releases.stackql.io/stackql/latest/stackql-mcp-darwin-universal.mcpb)
[Download Linux MCPB (x64)](https://releases.stackql.io/stackql/latest/stackql-mcp-linux-x64.mcpb)
[Download Windows MCPB](https://releases.stackql.io/stackql/latest/stackql-mcp-windows-x64.mcpb)

:::info

The StackQL MCP server is also listed on the [__Official MCP Registry__](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) as `io.github.stackql/stackql-mcp`.

:::

:::tip

The bundle is one of several ways to run the StackQL MCP server.  See [__Using StackQL with Claude Desktop__](/getting-started/claude-desktop) for the full Claude Desktop walkthrough, or [__Installing the MCP server__](#installing-the-mcp-server) for the npx, Docker, Python, CI and manual options.

:::

**ChatGPT**

### ChatGPT and Codex

  StackQL ships as a local plugin for the ChatGPT desktop app and the Codex CLI. The plugin runs the StackQL MCP server over stdio on your machine, so provider credentials never leave it. Node.js 18 or later is required; the plugin downloads the signed `stackql` binary on first use and verifies its SHA-256.

  **ChatGPT desktop app:** open **Settings -> Plugins -> Add -> Add from GitHub**, enter `stackql/stackql`, then install **StackQL** from the **Personal** section of the plugin directory and restart the app.

  **Codex CLI:**

  ```shell
  codex plugin marketplace add stackql/stackql --sparse .agents/plugins --sparse packaging/openai-plugin
  codex plugin add stackql@stackql
  ```

  Restart ChatGPT desktop or Codex, then try: *Use StackQL to install the GitHub provider if needed, then list the first five GitHub services.* Provider credentials go in `~/.stackql/.env` using each provider's standard environment variable names (for example `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`); after editing the file, ask the agent to call `reload_credentials`.

  **Without the plugin:** under **Settings -> Plugins -> MCPs -> Connect to a custom MCP**, choose **STDIO**, set the command to `npx` and add the arguments `-y` and `@stackql/mcp-server`. Supply provider credentials as environment variables on that form.

:::note

ChatGPT web cannot run a local stdio server, so the plugin is desktop and Codex only. StackQL is not yet in OpenAI's public plugin directory, which requires a hosted MCP endpoint; the marketplace install above is the supported route. An open ChatGPT desktop bug ([openai/codex#38162](https://github.com/openai/codex/issues/38162)) can hide local MCP tools from **Chat** sessions; Codex threads and the Codex CLI are unaffected.

:::

**Goose**

### Goose

  Goose runs stdio extensions directly, so the `npx` launcher is all you need (Node.js 18 or later).

  **Goose Desktop:** click the button below. Goose opens, shows the command it is about to run and asks you to confirm, then adds StackQL as an extension.

  Install in Goose Desktop

  The button is a `goose://` deep link; you can also paste it into your browser's address bar, or open it from a terminal with `open` (macOS), `start` (Windows) or `xdg-open` (Linux):

  ```
  goose://extension?cmd=npx&arg=-y&arg=%40stackql%2Fmcp-server&id=stackql&name=StackQL&description=Query%20and%20provision%20cloud%20and%20SaaS%20resources%20with%20SQL
  ```

  **Goose CLI:**

  ```shell
  goose session --with-extension "npx -y @stackql/mcp-server"
  ```

  or run `goose configure`, choose **Add Extension -> Command-line Extension**, and enter the same command. Provide provider credentials as the extension's environment variables when prompted.

:::note

Goose has retired its in-app extensions directory in favour of the [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql), where StackQL is listed as `io.github.stackql/stackql-mcp`. Once Goose ships its registry import, StackQL will be discoverable there without any further action.

:::

## Installing the MCP server

The StackQL MCP server lets AI agents query and provision cloud resources using StackQL. It ships through several channels - they all run the same server, so pick the channel that matches your client and your trust requirements. The options below are listed roughly in order of trust and ease.

### Marketplaces and directories

The server is published to the Official MCP Registry as `io.github.stackql/stackql-mcp`; the package registries below carry the distributable artifacts, and downstream directories pick the listing up from there.  

**Registries**

| Registry | Type | Published via | Listing | Notes |
|---|---|---|---|---|
| Official MCP Registry | Canonical metadata registry | `mcp-publisher` CLI + `server.json` | [`modelcontextprotocol.io/search`](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) [`modelcontextprotocol.io/direct`](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.stackql/stackql-mcp) | advertises all 7 package types (`mcpb x4`, `oci`, `npm`, `pypi`) |
| npm | Package registry | `npm publish` | [`@stackql/mcp-server`](https://www.npmjs.com/package/@stackql/mcp-server) | `npx` launcher |
| PyPI | Package registry | `twine upload` | [`stackql-mcp-server`](https://pypi.org/project/stackql-mcp-server/) | `uvx` / `pip` launcher |
| Docker Hub | Container registry | `docker buildx --push` | [`stackql/stackql-mcp`](https://hub.docker.com/r/stackql/stackql-mcp) | multi-arch `amd64` + `arm64` |
| GitHub Actions Marketplace | CI marketplace (`setup-stackql-mcp` action) | Public repo + release + marketplace listing | [`setup-stackql-mcp-server`](https://github.com/marketplace/actions/setup-stackql-mcp-server) | Verified publisher; [`stackql/setup-stackql-mcp`](https://github.com/stackql/setup-stackql-mcp) |

**Directories**

Directory and aggregator listings, in rough order of significance for discovery:

| Directory | Type | Listing |
|---|---|---|
| __Anthropic Connector Directory__ | Claude Desktop in-app directory | [claude.ai/directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) |
| __Cursor Directory__ | IDE client directory | [cursor.directory](https://cursor.directory/plugins/stackql-mcp-server) |
| __mcp.so__ | Largest aggregator | [mcp.so](https://mcp.so/server/stackql/stackql) |
| __PulseMCP__ | Discovery, registry backer | [pulsemcp](https://www.pulsemcp.com/servers/stackql) |
| __Glama.ai MCP__ | Searchable marketplace | [glama.ai](https://glama.ai/mcp/servers/stackql/stackql) |
| __mcpmarket.com__ | Aggregator | [mcpmarket](https://mcpmarket.com/server/stackql) |
| __mcpservers.org__ | Awesome-list site | [mcpservers.org](https://mcpservers.org/servers/stackql-mcp-server) |

### Prebuilt `.mcpb` bundle

**When to use:** Claude Desktop without Connector Directory access, or when you want to pin a specific version or verify checksums yourself before installing.  For most Claude Desktop users the [Anthropic Connector Directory](https://claude.ai/directory/connectors/ant.dir.gh.stackql.stackql) is the recommended installation method.

A prebuilt MCP Bundle is attached to every StackQL release for each platform:

```
https://releases.stackql.io/stackql/latest/stackql-mcp-<platform>.mcpb
```

where `<platform>` is one of `darwin-universal`, `windows-x64`, `linux-x64`, or `linux-arm64`. Download buttons for each platform are in the **Claude Desktop** tab under [Using with MCP clients](#using-with-mcp-clients). Each bundle has a matching `.sha256` checksum on the [release page](https://github.com/stackql/stackql/releases/latest). Verify it, then install via **Settings -> Extensions** in Claude Desktop:

```bash
shasum -a 256 -c stackql-mcp-darwin-universal.mcpb.sha256
```

See [Using StackQL with Claude Desktop](/getting-started/claude-desktop#install-from-a-downloaded-bundle) for the full walkthrough.

### Manual `claude_desktop_config.json`

**When to use:** you already have the `stackql` binary on your PATH and use Claude Desktop or any other stdio MCP client.

```json
{
  "mcpServers": {
    "stackql": {
      "command": "stackql",
      "args": [
        "mcp",
        "--mcp.server.type=stdio",
        "--approot", "/Users/you/.stackql",
        "--mcp.config", "{\"server\": {\"audit\": {\"disabled\": true}}}"
      ]
    }
  }
}
```

All three arguments are load-bearing:

- `--mcp.server.type=stdio` selects the stdio transport that editor-embedded clients speak.
- `--approot` points the provider cache at a writable directory. MCP clients may launch the server with the working directory set to `/`, which is not writable.
- `--mcp.config '{"server": {"audit": {"disabled": true}}}'` disables the audit log, which otherwise defaults its directory to the (possibly non-writable) working directory.

Add provider credentials with an `"env"` block and tune the safety contract with `"mode"` - see [Server modes](/command-line-usage/mcp#server-modes).

### `npx` (no install)

**When to use:** any Node environment, when you do not want a global StackQL install.

```json
{ "mcpServers": { "stackql": { "command": "npx", "args": ["-y", "@stackql/mcp-server"] } } }
```

The [`@stackql/mcp-server`](https://www.npmjs.com/package/@stackql/mcp-server) launcher downloads the signed `stackql` binary on first run, verifies its SHA-256, and caches it for subsequent runs.

### `uvx` / `pip` (Python)

**When to use:** a Python environment - the same launcher packaged for Python, sharing the binary cache the npx launcher populates.

```json
{ "mcpServers": { "stackql": { "command": "uvx", "args": ["stackql-mcp-server"] } } }
```

Or install it into the current environment with `pip install stackql-mcp-server` (Python 3.9+). The package is [`stackql-mcp-server`](https://pypi.org/project/stackql-mcp-server/) on PyPI.

### Docker

**When to use:** a containerised or otherwise isolated runtime. The image is multi-arch (amd64 and arm64).

```bash
docker run -i --rm stackql/stackql-mcp
```

As a client configuration:

```json
{ "mcpServers": { "stackql": { "command": "docker", "args": ["run", "-i", "--rm", "stackql/stackql-mcp"] } } }
```

The image is [`stackql/stackql-mcp`](https://hub.docker.com/r/stackql/stackql-mcp) on Docker Hub.

### CI and agentic workflows (GitHub Actions)

**When to use:** run the server inside a GitHub Actions job so an agent can query - and, if you allow it, act on - your cloud as part of CI.

[`stackql/setup-stackql-mcp@v1`](https://github.com/marketplace/actions/setup-stackql-mcp-server) installs the binary and writes an MCP config (defaulting to `read_only` mode). Pass that config to [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action) through `claude_args`:

```yaml
- id: stackql
  uses: stackql/setup-stackql-mcp@v1
  with:
    auth: '{"github":{"type":"null_auth"}}'

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: |
      Using stackql, list the public repositories in the stackql org and
      summarise them as a markdown table.
    claude_args: |
      --mcp-config ${{ steps.stackql.outputs.mcp-config-file }}
      --allowedTools 'mcp__stackql__*'
```

See the [action README](https://github.com/stackql/setup-stackql-mcp) for more agentic recipes (cloud audits, cost estimates, and so on).

### Embedded MCP

**When to use:** you are building an agentic app and want to vendor the MCP server into your own binary - no `npx`, no separate install, no runtime dependency.

Native libraries spawn the signed `stackql` binary over stdio behind each language's official MCP SDK client, so your app gets the same governed SQL interface to every provider in the registry. Each library defaults to `read_only` - escalation to a writable mode is always explicit - and can either download-and-verify the binary on first run or vendor it into your build for a single self-contained executable. The full per-language API is in the [Embedded MCP reference](/mcp/embedded).

**Rust**

The `stackql-mcp` crate spawns the binary behind an `rmcp` client. The default `sidecar` feature downloads and verifies the binary on first run; the `vendored` feature embeds it with `include_bytes!` for a single self-contained binary. MSRV Rust 1.88.

```toml
# Cargo.toml
stackql-mcp = "0.1"
```

```rust
use stackql_mcp::{Mode, StackqlMcp};

let server = StackqlMcp::builder()
    .mode(Mode::ReadOnly)
    .start()
    .await?;
let tools = server.list_all_tools().await?;
```

[View on GitHub](https://github.com/stackql/stackql-mcp-rs)
[View on crates.io](https://crates.io/crates/stackql-mcp)

Full reference: [Embedded MCP: Rust](/mcp/embedded/rust).

**Go**

The `stackql-mcp-go` library spawns the binary behind the official Go MCP SDK client. Vendor the binary with `go:embed` for a single self-contained binary, or let it download and verify on first run. Starts in `read_only` mode by default.

```bash
go get github.com/stackql/stackql-mcp-go
```

```go
import (
    "context"
    stackqlmcp "github.com/stackql/stackql-mcp-go/embed"
)

client, err := stackqlmcp.StartServer(ctx, stackqlmcp.Options{
    Binary: StackqlMCPBinary(),
})
defer client.Close()
```

[View on GitHub](https://github.com/stackql/stackql-mcp-go)
[View on pkg.go.dev](https://pkg.go.dev/github.com/stackql/stackql-mcp-go)

Full reference: [Embedded MCP: Go](/mcp/embedded/go).

**Kotlin / JVM**

The `io.stackql:stackql-mcp` library spawns the binary behind the official Kotlin MCP SDK client, and a companion Gradle plugin wires the same launch into a build. Requires JDK 17 and Kotlin 2.x.

```kotlin
dependencies {
    implementation("io.stackql:stackql-mcp:0.1.0")
}
```

```kotlin
import io.stackql.mcp.Mode
import io.stackql.mcp.StackqlMcp

val server = StackqlMcp.builder().mode(Mode.ReadOnly).start()
server.use {
    val tools = server.client.listTools().tools
}
```

[View on GitHub](https://github.com/stackql/stackql-mcp-kotlin)

Full reference: [Embedded MCP: Kotlin / JVM](/mcp/embedded/kotlin).

**.NET**

The `StackQL.Mcp` package spawns the binary behind the official C# MCP SDK client. Sidecar by default, or vendor the bundle as a build resource for a self-contained executable. Requires .NET 8 or later.

```bash
dotnet add package StackQL.Mcp
```

```csharp
using StackQL.Mcp;

await using var server = await StackqlMcp.CreateBuilder()
    .WithMode(StackqlMode.ReadOnly)
    .StartAsync();

var tools = await server.ListToolsAsync();
```

[View on GitHub](https://github.com/stackql/stackql-mcp-dotnet)

Full reference: [Embedded MCP: .NET / C#](/mcp/embedded/dotnet).

**Gleam**

The `stackql_mcp` library targets the Erlang/BEAM runtime and exposes the server as an OTP child via `child_spec()`, so it can sit inside your own supervision tree. Starts in `read_only` mode by default.

```bash
gleam add stackql_mcp
```

```gleam
import envoy
import stackql_mcp

let assert Ok(server) =
  stackql_mcp.start(
    config: stackql_mcp.default_config(),
    home: "/home/u", os: "linux", arch: "x86_64",
    getenv: envoy.get,
  )
let assert Ok(tools) = stackql_mcp.list_tools(server)
```

[View on GitHub](https://github.com/stackql/stackql-mcp-gleam)

Full reference: [Embedded MCP: Gleam](/mcp/embedded/gleam).

**Swift**

The `stackql-mcp-swift` package spawns the binary behind the official Swift MCP SDK client. The `darwin-universal` binary is Developer ID signed and Apple-notarised, so you can bundle it inside a signed `.app` and keep the app's notarisation valid. Requires macOS 13+ and Swift 6.1 (Xcode 16.3+).

```swift
// Package.swift
.package(url: "https://github.com/stackql/stackql-mcp-swift.git", from: "0.1.0")
```

```swift
import StackQLMCP

var options = Options()
options.mode = .readOnly

let server = try await StackQLServer.start(options)
let tools = try await server.listToolNames()
await server.stop()
```

[View on GitHub](https://github.com/stackql/stackql-mcp-swift)

Full reference: [Embedded MCP: Swift](/mcp/embedded/swift).

### Trust model

The same security properties hold across every channel:

- The embedded `stackql` binary is Authenticode-signed (Windows) and Apple-notarised (macOS).
- Every `.mcpb` bundle ships with a published SHA-256 checksum on the release page.
- The `npx` and `uvx` launchers verify the downloaded binary's SHA-256 before first use.
- The [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=stackql) entry attests the per-platform hashes.

## Using GitHub Actions

[StackQL GitHub Actions](https://github.com/stackql/stackql-actions-demo) 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](https://github.com/marketplace/actions/stackql-deploy)

__Example usage__

```yaml
...
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@v6

      - name: Deploy a Stack
        uses: stackql/stackql-deploy-action@v2
        with:
          command: 'build'
          stack_dir: 'examples/k8s-the-hard-way'
          stack_env: 'dev'
          env_vars: |
            GOOGLE_PROJECT=stackql-k8s-the-hard-way-demo
            GOOGLE_REGION=australia-southeast1
```

**setup-stackql**

### `setup-stackql`

Setup StackQL in your GitHub Actions workflow.  

[View on the GitHub Marketplace](https://github.com/marketplace/actions/setup-stackql)

__Example usage__

```yaml
- name: setup StackQL
  uses: stackql/setup-stackql@v2
  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 }}
```

**setup-stackql-mcp**

### `setup-stackql-mcp`

Install the StackQL MCP server in your GitHub Actions workflow.  The action installs the signed binary and writes an `mcpServers` config (defaulting to `read_only` mode) that an agentic step such as `anthropics/claude-code-action` consumes via `claude_args`.

[View on the GitHub Marketplace](https://github.com/marketplace/actions/setup-stackql-mcp-server)
[View on GitHub](https://github.com/stackql/setup-stackql-mcp)

__Example usage__

```yaml
- id: stackql
  uses: stackql/setup-stackql-mcp@v1
  with:
    auth: '{"github":{"type":"null_auth"}}'

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: |
      Using stackql, list the public repositories in the stackql org and
      summarise them as a markdown table.
    claude_args: |
      --mcp-config ${{ steps.stackql.outputs.mcp-config-file }}
      --allowedTools 'mcp__stackql__*'
```

**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](https://github.com/marketplace/actions/stackql-exec)

__Example usage__

```yaml
- name: exec github example
  uses: stackql/stackql-exec@v2
  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](https://github.com/marketplace/actions/stackql-assert)

__Example usage__

```yaml
- name: Use test query string and expected rows
  uses: stackql/stackql-assert@v2
  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__](https://pypi.org/project/pystackql/), documentation for the `pystackql` package is available via [__Read the Docs__](https://pystackql.readthedocs.io/en/latest/). To install the `pystackql` package, run the following command:

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

```python
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)
```