Terrakube CLI

For full CLI reference documentation, visit our official guide at https://docs.terrakube.io/user-guide/terrakube-cli.

---

Table of Contents

• Download & Installation
  • Snap Package (Ubuntu / Linux)
  • Linux & macOS
  • Windows
• Adding Terrakube CLI to PATH
  • Linux & macOS
  • Windows
• Building & Testing from Source
  • Compiling the Binary
  • Building Snap Package Locally
  • Running Unit Tests
  • Running End-to-End (BATS) Tests
• Quick Start Guide
  • 1. Login to Terrakube
  • 2. Create an Organization
  • 3. Create an Admin Team & Assign Permissions
  • 4. Create a Workspace (OpenTofu & Docker Compose)
  • 5. Add Workspace Environment Variables & Tags
  • 6. Configure Notifications (Slack / Teams / Webhook)
• Contributing
• Security

---

Download & Installation

You can download pre-compiled binaries directly from our GitHub Releases page, or install via Snap on Linux/Ubuntu.

Snap Package (Ubuntu / Linux)

You can install the local .snap package:

sudo snap install --dangerous terrakube-cli_*.snap

Both terrakube and terrakube-cli commands will be available:

terrakube --version
terrakube-cli --help

Linux & macOS (Bash / Zsh)

Download the binary using curl or wget:

# Example: Download latest Linux amd64 binary
curl -sSL -o terrakube https://github.com/terrakube-io/terrakube-cli/releases/latest/download/terrakube-linux-amd64
chmod +x terrakube

Windows (PowerShell)

Download the binary using PowerShell:

# Download latest Windows amd64 binary
Invoke-WebRequest -Uri "https://github.com/terrakube-io/terrakube-cli/releases/latest/download/terrakube-windows-amd64.exe" -OutFile "terrakube.exe"

---

Adding Terrakube CLI to PATH

To run terrakube from any directory, add the binary location to your system's PATH environment variable.

Linux & macOS

System-Wide Installation (Recommended)

Move the compiled or downloaded binary to /usr/local/bin:

sudo mv terrakube /usr/local/bin/
terrakube --version

User-Level Installation

If you prefer placing the binary in a custom folder (e.g., ~/.local/bin or ~/bin):

mkdir -p ~/.local/bin
mv terrakube ~/.local/bin/

Add the following line to your shell configuration file (~/.bashrc or ~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

Reload shell settings:

source ~/.bashrc   # Or source ~/.zshrc

---

Windows

Option A: PowerShell (Command Line)

To permanently append the folder containing terrakube.exe to your user PATH:

# Assuming terrakube.exe is placed in C:\Tools\terrakube
$targetDir = "C:\Tools\terrakube"
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$currentPath;$targetDir", "User")

Restart PowerShell and verify:

terrakube --version

Option B: Windows GUI (System Properties)

1. Move terrakube.exe to a permanent folder (e.g., C:\Tools\terrakube).
2. Press Win + R, type sysdm.cpl, and press Enter.
3. Open the Advanced tab and click Environment Variables.
4. Under User variables, select Path and click Edit.
5. Click New and add the folder path (e.g., C:\Tools\terrakube).
6. Click OK to save and restart your command prompt or terminal.

---

Building & Testing from Source

Prerequisites

• Go 1.22 or higher

Compiling the Binary

Clone the repository and compile using go build:

git clone https://github.com/terrakube-io/terrakube-cli.git
cd terrakube-cli
go build -o terrakube main.go

Verify compilation:

./terrakube --help

Building Snap Package Locally

To build the Snap package on Ubuntu/Linux:

1. Install snapcraft:

   sudo snap install snapcraft --classic

2. Build the snap:

   # Build directly in container (LXD/Multipass):
   snapcraft
   
   # Or build locally in destructive mode:
   snapcraft --destructive-mode

3. Install the locally generated .snap package:

   sudo snap install --dangerous terrakube-cli_*.snap

Running Unit Tests

Run unit tests across all Golang packages:

go test ./...

Running End-to-End (BATS) Tests

Terrakube CLI includes comprehensive end-to-end integration tests written using BATS.

Important

To execute the E2E test suite, you must have a running Terrakube Server test instance. Set the API endpoint URL (e.g., https://terrakube-api.platform.local) and an Admin Personal Access Token (PAT) in your environment variables:

export TERRAKUBE_API_URL="https://terrakube-api.platform.local"
export TERRAKUBE_PAT="XXXXXXXXXXXXX"  # Replace with a valid Terrakube Admin Personal Access Token

Execute the E2E operations test suite:

bats tests/e2e_operations.bats

---

Quick Start Guide

This step-by-step example demonstrates standard Terrakube CLI operations based on end-to-end workflows.

1. Login to Terrakube

Authenticate against your Terrakube server using your API URL and Personal Access Token (PAT):

terrakube login -a "https://terrakube-api.platform.local" -t "XXXXXXXXXXXXX"

2. Create an Organization

Create a new organization configured for remote execution:

terrakube organization create \
  --name "demo-org" \
  --description "Production Engineering Organization" \
  --execution-mode "remote" \
  --output json

Save the returned organization ID (e.g., 09e86337-b6bb-49e0-82aa-c114ad0f41ab) for subsequent operations.

3. Create an Admin Team & Assign Permissions

Create a TERRAKUBE_ADMIN team inside your organization with admin permissions:

terrakube team create \
  -o "09e86337-b6bb-49e0-82aa-c114ad0f41ab" \
  --name "TERRAKUBE_ADMIN" \
  --role "Admin" \
  --manage-workspace \
  --manage-module \
  --manage-provider \
  --manage-state \
  --manage-collection \
  --manage-vcs \
  --manage-template \
  --manage-job \
  --plan-job \
  --approve-job \
  --output table

4. Create a Workspace (OpenTofu & Docker Compose)

Create a new workspace using OpenTofu (tofu) linked to the repository terrakube-docker-compose:

terrakube workspace create \
  -o "09e86337-b6bb-49e0-82aa-c114ad0f41ab" \
  --name "docker-compose-infra" \
  --description "Docker Compose OpenTofu Workspace" \
  --source "https://github.com/terrakube-io/terrakube-docker-compose" \
  --branch "main" \
  --folder "/" \
  --iac-type "tofu" \
  --iac-version "1.12.5" \
  --execution-mode "remote" \
  --output json

5. Add Workspace Environment Variables & Tags

Add Environment Variables

Create environment variables for the workspace:

terrakube variable create \
  -o "09e86337-b6bb-49e0-82aa-c114ad0f41ab" \
  -w "<WORKSPACE_ID>" \
  --key "ENVIRONMENT" \
  --value "production" \
  --category "ENV" \
  --output table

Create and Associate Workspace Tags

1. Create an organization-level tag:

   terrakube tag create \
     -o "09e86337-b6bb-49e0-82aa-c114ad0f41ab" \
     --name "production" \
     --output json

2. Associate the tag with your workspace:

   terrakube workspace-tag create \
     -o "09e86337-b6bb-49e0-82aa-c114ad0f41ab" \
     -w "<WORKSPACE_ID>" \
     --tag-id "<TAG_ID>" \
     --output table

6. Configure Notifications (Slack / Teams / Webhook)

1. Create an organization or workspace notification configuration:

   terrakube notification-configuration create \
     -o "09e86337-b6bb-49e0-82aa-c114ad0f41ab" \
     --name "slack-alerts" \
     --channel-type "SLACK" \
     --destination-url "https://hooks.slack.com/services/T00/B00/X00" \
     --message-style "DETAILED" \
     --active \
     --output json

2. Add a trigger on job completion or failure:

   terrakube notification-trigger create \
     -o "09e86337-b6bb-49e0-82aa-c114ad0f41ab" \
     --notification-configuration "<NOTIFICATION_CONFIGURATION_ID>" \
     --job-status "completed" \
     --output table

---

Contributing

We welcome contributions from the community! Please check out our Contributing Guidelines for information on setting up your environment, code formatting conventions, submitting pull requests, and registering new CLI commands.

---

Security

Security vulnerabilities or concerns should be reported responsibly. Please read our Security Policy for details on supported versions and reporting procedures.