Skip to main content

Install the CLI

The AI Gateway CLI is a command-line tool for deploying and managing AI Gateway in private cloud clusters.

Official CLI Installation Page: https://cequence.gitlab.io/ai-gateway/cli/

Installation from GitLab Pages​

The CLI can be installed directly from the official installation page:

Quick Install (Latest Stable Release):

curl -sSL https://cequence.gitlab.io/ai-gateway/cli/install.sh | sh

Install Latest Snapshot (Development Build):

curl -sSL https://cequence.gitlab.io/ai-gateway/cli/install.sh | sh -s -- snapshot

Install Specific Version:

curl -sSL https://cequence.gitlab.io/ai-gateway/cli/install.sh | sh -s -- v1.0.0

Installation Process​

The installer will:

  1. Detect your platform

    • Automatically detects your OS (Linux, macOS, Windows) and architecture (x86_64, ARM64)

  2. Download the appropriate binary

    • Downloads the correct binary for your platform from GitLab Pages
    • Supports Linux, macOS (Intel and Apple Silicon), and Windows

  3. Install to system path

    • Installs to /usr/local/bin (or ~/.local/bin if no sudo access)
    • Makes the binary executable

  4. Verify installation

    • Runs aigateway version to confirm installation

Manual Installation​

If you prefer manual installation:

  1. Download the binary from https://cequence.gitlab.io/ai-gateway/cli/

    • Select your platform (Linux x86_64, Linux ARM64, macOS Intel, macOS Apple Silicon, Windows)
    • Download the latest release or snapshot

  2. Extract the archive

    # Linux/macOS
    tar -xzf aigateway_<version>_<OS>_<ARCH>.tar.gz

    # Windows
    unzip aigateway_<version>_Windows_<ARCH>.zip

  3. Move to PATH

    # Linux/macOS
    sudo mv aigateway /usr/local/bin/
    chmod +x /usr/local/bin/aigateway

    # Or without sudo
    mkdir -p ~/.local/bin
    mv aigateway ~/.local/bin/
    export PATH="$HOME/.local/bin:$PATH"

  4. Verify installation

    aigateway version

Post-Installation Setup​

After installation, initialize the CLI with your tenant and pool configuration.

If you've already created a pool, copy the initialization command directly from the pool detail page — see Pool Configuration Pending banner. The copied command includes all required parameters:

aigateway init --tenant <your-tenant-id> --pool-id <your-pool-id> --namespace <your-namespace>

Paste and run it in your terminal, then continue with authentication:

# Authenticate using OAuth device flow
aigateway login

# Verify configuration
aigateway config

Option 2: Manual Initialization​

If you prefer to initialize manually or don't have a pool created yet:

# Initialize CLI with your tenant ID
aigateway init --tenant <your-tenant-id>

# Authenticate using OAuth device flow
aigateway login

# Verify configuration
aigateway config

Non-interactive CI/CD setup​

The interactive aigateway login device flow above is intended for developer workstations. For CI/CD pipelines, GitOps controllers (Argo CD, Flux), and any other automated path, the CLI runs non-interactively, driven entirely by environment variables.

Instead of the OAuth device flow, the CLI authenticates with OAuth 2.0 client credentials. Generate a client ID and secret in the portal at Settings → Users → API Credentials (the same place User Management lives). Create a new entry and assign it the Super Admin role so it can install and manage pools, then copy the client ID and secret — the secret is shown only once at creation. Credentials are scoped to your tenant and can be rotated independently of any individual user.

Set the following in your pipeline:

VariableRequiredPurpose
AIGATEWAY_CI_MODEYesSet to true. Switches authentication to OAuth client credentials (so no interactive device-flow prompt) and uses AIGATEWAY_CLIENT_ID / AIGATEWAY_CLIENT_SECRET for the API.
AIGATEWAY_TENANTYesYour tenant ID (same value used with aigateway init --tenant).
AIGATEWAY_CLIENT_IDYesOAuth client ID provided by Cequence.
AIGATEWAY_CLIENT_SECRETYesOAuth client secret. Store in your pipeline's secret store (never in source).
AIGATEWAY_NAMESPACENoTarget namespace; defaults to the pool's configured namespace.

Pipeline deployment:

export AIGATEWAY_CI_MODE=true
export AIGATEWAY_TENANT="<your-tenant>"
export AIGATEWAY_CLIENT_ID="<oauth-client-id>"
export AIGATEWAY_CLIENT_SECRET=$PIPELINE_CLIENT_SECRET   # injected from your pipeline secret store
export AIGATEWAY_NAMESPACE="<pool-namespace>"

aigateway init --tenant "$AIGATEWAY_TENANT" --pool-id <pool-id> --namespace "$AIGATEWAY_NAMESPACE"
aigateway deploy install --wait
aigateway status --json

Commands that support JSON output (aigateway status, aigateway logs, aigateway events, aigateway cluster permissions, aigateway config show) accept a --json flag — pass it explicitly so the pipeline can gate on machine-readable output (for example jq '.summary.Unhealthy == 0').

GitLab CI example:

deploy_ai_gateway:
  stage: deploy
  image: alpine:latest
  variables:
    AIGATEWAY_CI_MODE: "true"
    AIGATEWAY_TENANT: "<your-tenant>"
    AIGATEWAY_CLIENT_ID: "<oauth-client-id>"
    AIGATEWAY_NAMESPACE: "ai-gateway"
    # AIGATEWAY_CLIENT_SECRET must be defined as a masked, protected CI/CD variable
  before_script:
    - curl -sSL https://cequence.gitlab.io/ai-gateway/cli/install.sh | sh
  script:
    - aigateway init --tenant "$AIGATEWAY_TENANT" --pool-id "$POOL_ID" --namespace "$AIGATEWAY_NAMESPACE"
    - aigateway deploy install --wait
    - aigateway status --json
  only:
    - main

Equivalent patterns work for GitHub Actions, Azure DevOps, Jenkins, and any other CI system — set the same AIGATEWAY_* variables in the job environment.

GitOps (Argo CD / Flux). GitOps controllers expect to manage Kubernetes manifests directly, while AI Gateway's manifests are generated and reconciled by the Operator from the control plane. The recommended pattern is:

  1. Treat the install step as a GitOps-managed Job, not a GitOps-managed manifest set. In your Git repository, commit a small Kubernetes Job (or Argo CD PreSync hook / Flux Kustomization) that runs aigateway deploy install --wait in CI/CD mode. Argo/Flux applies the Job; the Job invokes the CLI; the CLI talks to the control plane and reconciles the pool.
  2. Bootstrap secrets through your usual GitOps secrets flow (Sealed Secrets, SOPS, ESO, External Secrets via Argo, etc.) so the AIGATEWAY_CLIENT_SECRET, image-pull credentials, Redis password, and TLS material are all in place before the Job runs.
  3. Pool configuration is owned by the control plane, not Git. Resource limits, ingress, image versions, and Redis mode are managed in the portal so that pool drift is reconciled by the Operator. Treat Git as the source of truth for the bootstrap, and the control plane as the source of truth for what runs.

This keeps the GitOps controller's surface small (one Job, plus secrets) and avoids fighting the Operator over ownership of Armor, Redis, and ingress resources.

Troubleshooting Installation​

Issue: Binary not found after installation

  • Check if the installation directory is in your PATH: 
    echo $PATH | grep -E "(/usr/local/bin|~/.local/bin)"
  • Add to PATH if needed: 
    # Add to ~/.bashrc, ~/.zshrc, or ~/.profile
    export PATH="$HOME/.local/bin:$PATH"

Issue: Permission denied

  • Make sure the binary is executable: 
    chmod +x /usr/local/bin/aigateway

Issue: Download fails

  • Check network connectivity
  • Verify GitLab Pages is accessible: curl https://cequence.gitlab.io/ai-gateway/cli/
  • Try installing from a different network or use a VPN
Last updated on