ZTiAWS Installation Guide

ztictl is the modern, cross-platform AWS Systems Manager CLI tool that simplifies AWS instance management.

📦 Primary Tool: We recommend using the Go binary (ztictl) for new installations. The bash tools are maintained for legacy users but are being phased out.

Prerequisites

AWS CLI configured with appropriate credentials
EC2 instances with SSM agent installed and proper IAM roles

Quick Install (Recommended)

Linux/macOS - One-liner with automatic platform detection:

curl -L -o /tmp/ztictl "https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')" && chmod +x /tmp/ztictl && sudo mv /tmp/ztictl /usr/local/bin/ztictl && ztictl --version

Windows PowerShell - Full setup:

# Download and setup ztictl
Invoke-WebRequest -Uri "https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-windows-amd64.exe" -OutFile "ztictl.exe"
$toolsDir = "$env:USERPROFILE\Tools"
if (-not (Test-Path $toolsDir)) { New-Item -ItemType Directory -Path $toolsDir }
Move-Item "ztictl.exe" "$toolsDir\ztictl.exe"

# Add to PATH permanently
$currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
if ($currentPath -notlike "*$toolsDir*") {
    $newPath = $currentPath + ";$toolsDir"
    [Environment]::SetEnvironmentVariable("PATH", $newPath, "User")
    $env:PATH = $newPath
}

# Verify installation
ztictl --version

Platform-Specific Installation

Linux

AMD64 (Intel/AMD):

curl -L -o /tmp/ztictl https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-linux-amd64
chmod +x /tmp/ztictl && sudo mv /tmp/ztictl /usr/local/bin/ztictl

ARM64 (ARM processors):

curl -L -o /tmp/ztictl https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-linux-arm64
chmod +x /tmp/ztictl && sudo mv /tmp/ztictl /usr/local/bin/ztictl

macOS

Intel Macs:

curl -L -o /tmp/ztictl https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-darwin-amd64
chmod +x /tmp/ztictl && sudo mv /tmp/ztictl /usr/local/bin/ztictl

Apple Silicon (M1/M2/M3):

curl -L -o /tmp/ztictl https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-darwin-arm64
chmod +x /tmp/ztictl && sudo mv /tmp/ztictl /usr/local/bin/ztictl

Windows

Option 1: Manual Download

Download: https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-windows-amd64.exe
Rename to ztictl.exe
Follow the PATH setup instructions below

Option 2: PowerShell (Recommended)

# Download
Invoke-WebRequest -Uri "https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-windows-amd64.exe" -OutFile "ztictl.exe"

# Setup Tools directory
$toolsDir = "$env:USERPROFILE\Tools"
if (-not (Test-Path $toolsDir)) { New-Item -ItemType Directory -Path $toolsDir }
Move-Item "ztictl.exe" "$toolsDir\ztictl.exe"

# Add to PATH (see Windows PATH setup below)

Windows PATH Setup

Method 1: PowerShell (Recommended)

$toolsDir = "$env:USERPROFILE\Tools"
$currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
if ($currentPath -notlike "*$toolsDir*") {
    $newPath = $currentPath + ";$toolsDir"
    [Environment]::SetEnvironmentVariable("PATH", $newPath, "User")
    $env:PATH = $newPath  # Update current session
}

Method 2: GUI

Press Win + R, type sysdm.cpl, press Enter
Click "Environment Variables"
Under "User variables", select "Path" and click "Edit"
Click "New" and add your tools directory path (e.g., C:\Users\YourName\Tools)
Click "OK" on all dialogs
Restart PowerShell/Command Prompt

Usage

Quick Start

# Check system requirements
ztictl config check

# Configure AWS authentication
ztictl auth configure

# List instances in a region
ztictl ssm list --region ca-central-1

# Connect to an instance
ztictl ssm connect i-1234567890abcdef0 --region ca-central-1

# Execute remote commands
ztictl ssm exec i-1234567890abcdef0 "uptime" --region ca-central-1

# Advanced file transfers (automatic S3 routing for large files)
ztictl ssm transfer upload i-1234567890abcdef0 large-file.zip /opt/data.zip --region ca-central-1

Configuration Management

# Show current configuration
ztictl config show

# Validate setup
ztictl config validate

# Get help
ztictl --help
ztictl ssm --help

Updating ZTiAWS

Updating ztictl

Simple Update (Recommended):

# Download to a temporary location to avoid conflicts
curl -L -o /tmp/ztictl "https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')" && chmod +x /tmp/ztictl && sudo mv /tmp/ztictl /usr/local/bin/ztictl && ztictl --version

Step-by-step Update:

# 1. Download latest version to temporary location
curl -L -o /tmp/ztictl "https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')"

# 2. Make it executable
chmod +x /tmp/ztictl

# 3. Replace the old version
sudo mv /tmp/ztictl /usr/local/bin/ztictl

# 4. Verify the update
ztictl --version

Windows Update:

# Download to temporary location
$tempFile = "$env:TEMP\ztictl.exe"
Invoke-WebRequest -Uri "https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-windows-amd64.exe" -OutFile $tempFile

# Replace existing binary
$toolsDir = "$env:USERPROFILE\Tools"
Move-Item $tempFile "$toolsDir\ztictl.exe" -Force

# Verify update
ztictl --version

Alternative: Platform-specific updates

Linux AMD64:

curl -L -o /tmp/ztictl https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-linux-amd64 && chmod +x /tmp/ztictl && sudo mv /tmp/ztictl /usr/local/bin/ztictl

Linux ARM64:

curl -L -o /tmp/ztictl https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-linux-arm64 && chmod +x /tmp/ztictl && sudo mv /tmp/ztictl /usr/local/bin/ztictl

macOS Intel:

curl -L -o /tmp/ztictl https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-darwin-amd64 && chmod +x /tmp/ztictl && sudo mv /tmp/ztictl /usr/local/bin/ztictl

macOS Apple Silicon:

curl -L -o /tmp/ztictl https://github.com/zsoftly/ztiaws/releases/latest/download/ztictl-darwin-arm64 && chmod +x /tmp/ztictl && sudo mv /tmp/ztictl /usr/local/bin/ztictl

Troubleshooting Updates:

If you get "Is a directory" error:

# This happens when there's a directory named 'ztictl' in current folder
# Solution: Always download to /tmp/ as shown above

If you get "cannot overwrite non-directory" error:

# Check what ztictl currently is
file /usr/local/bin/ztictl
ls -la /usr/local/bin/ztictl

# If it's somehow a directory, remove it first
sudo rm -rf /usr/local/bin/ztictl
# Then retry the installation

To check current version before updating:

ztictl --version

To install a specific version (if needed):

# Replace v2.1.0 with desired version
curl -L -o /tmp/ztictl "https://github.com/zsoftly/ztiaws/releases/download/v2.1.0/ztictl-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')" && chmod +x /tmp/ztictl && sudo mv /tmp/ztictl /usr/local/bin/ztictl

Updating Legacy Bash Tools

Navigate to your cloned repository directory and pull the latest changes:

cd /path/to/ztiaws
git pull origin main
chmod +x ssm authaws

If updating from pre-March 2025 (when repository was named "quickssm"), see docs/deprecated_update_instructions.md.

Building from Source

Building ztictl

If you prefer to build ztictl from source instead of using pre-built binaries:

Prerequisites:

Go 1.24 or later
Git

Build Steps:

# Clone the repository
git clone https://github.com/zsoftly/ztiaws.git
cd ztiaws/ztictl

# Build for current platform
make build-local
# Binary will be at: ./bin/ztictl

# Or build manually with Go
go build -o ztictl cmd/ztictl/*.go

# Install to system
sudo mv ./bin/ztictl /usr/local/bin/ztictl
# Or: sudo mv ./ztictl /usr/local/bin/ztictl

# Verify installation
ztictl --version

Cross-platform builds:

# Build for all platforms
make build

# Build for specific platform
GOOS=windows GOARCH=amd64 go build -o ztictl.exe cmd/ztictl/*.go
GOOS=linux GOARCH=arm64 go build -o ztictl-linux-arm64 cmd/ztictl/*.go
GOOS=darwin GOARCH=arm64 go build -o ztictl-darwin-arm64 cmd/ztictl/*.go

Legacy Bash Tools (Deprecated)

⚠️ Deprecation Notice: The bash tools (ssm and authaws) are being phased out in favor of the Go binary. They remain available for existing users but new features will only be added to ztictl.

If you need to use the legacy bash tools:

For End Users (Simple Installation):

# Step 1: Download
git clone https://github.com/zsoftly/ztiaws.git
cd ztiaws

# Step 2: Install (no build tools required)
./01_install.sh

# Step 3: Verify
authaws --check
ssm --help

The installation script automatically:

✅ Installs authaws and ssm commands globally
✅ Copies all required modules to /usr/local/bin/src/
✅ Sets up proper permissions
✅ Verifies installation works correctly

To uninstall: ./02_uninstall.sh

For Developers (Development Setup):

# Clone repository
git clone https://github.com/zsoftly/ztiaws.git
cd ztiaws

# Development environment setup
make dev          # Sets up development environment
make test         # Run shellcheck and basic tests
make clean        # Clean up temporary files

# Development testing
./authaws --check  # Test local development version
./ssm --help       # Test local development version

Manual Installation (Alternative):

# Clone repository
git clone https://github.com/zsoftly/ztiaws.git
cd ztiaws

# Make executable
chmod +x ssm authaws

# Add to PATH
echo 'export PATH="$PATH:'$(pwd)'"' >> ~/.bashrc  # bash
echo 'export PATH="$PATH:'$(pwd)'"' >> ~/.zshrc   # zsh
source ~/.bashrc  # or ~/.zshrc

# Verify
ssm check
authaws check

Basic Usage:

# List instances
ssm cac1  # Canada Central region

# Connect to instance
ssm i-1234567890abcdef0

# Authenticate with AWS SSO
authaws

Troubleshooting

Command Not Found

# Check installation
which ztictl
ztictl --version

# Check PATH (Linux/macOS)
echo $PATH | grep -o "/usr/local/bin"

# Check PATH (Windows)
echo $env:PATH.Split(';') | Select-String "Tools"

Permission Issues

# Linux/macOS: Ensure executable
sudo chmod +x /usr/local/bin/ztictl

# Windows: Check execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Architecture Issues

# Check your system architecture
uname -m        # Linux/macOS
$env:PROCESSOR_ARCHITECTURE  # Windows

# Common mappings:
# x86_64 / AMD64 → use amd64 binary
# aarch64 / arm64 → use arm64 binary

AWS Configuration

# Verify AWS CLI setup
aws --version
aws configure list

# Check SSM plugin (for ztictl)
ztictl config check

Why Choose ztictl?

🌍 Cross-platform: Native binaries for Linux, macOS, and Windows
⚡ Enhanced performance: No runtime dependencies, faster execution
🔒 Advanced security: Comprehensive IAM management and automatic cleanup
📁 Smart file transfers: Automatic routing via S3 for large files
🛠️ Modern CLI: Flag-based interface with comprehensive help
📊 Better logging: Thread-safe, timestamped logs with debug capabilities

Migrate from bash tools by simply installing ztictl and using similar commands with modern flag syntax!

Navigation Menu

Uh oh!

ZTiAWS Installation Guide

Prerequisites

Quick Install (Recommended)

Platform-Specific Installation

Linux

macOS

Windows

Windows PATH Setup

Usage

Quick Start

Configuration Management

Updating ZTiAWS

Updating ztictl

Updating Legacy Bash Tools

Building from Source

Building ztictl

Legacy Bash Tools (Deprecated)

For End Users (Simple Installation):

For Developers (Development Setup):

Manual Installation (Alternative):

Troubleshooting

Command Not Found

Permission Issues

Architecture Issues

AWS Configuration

Why Choose ztictl?

Uh oh!

FilesExpand file tree

INSTALLATION.md

Latest commit

History

INSTALLATION.md

File metadata and controls

ZTiAWS Installation Guide

Prerequisites

Quick Install (Recommended)

Platform-Specific Installation

Linux

macOS

Windows

Windows PATH Setup

Usage

Quick Start

Configuration Management

Updating ZTiAWS

Updating ztictl

Updating Legacy Bash Tools

Building from Source

Building ztictl

Legacy Bash Tools (Deprecated)

For End Users (Simple Installation):

For Developers (Development Setup):

Manual Installation (Alternative):

Troubleshooting

Command Not Found

Permission Issues

Architecture Issues

AWS Configuration

Why Choose ztictl?