Skip to content

CLI Reference

Complete documentation for all Tinkero CLI commands.

Table of Contents

  1. Installation
  2. Commands Overview
  3. tinkero setup
  4. tinkero config
  5. tinkero health
  6. tinkero cleanup
  7. Exit Codes
  8. Environment Variables

Installation

Download Pre-built Binary

# Linux (amd64)
wget https://github.com/yourusername/tinkero/releases/latest/download/tinkero-linux-amd64
chmod +x tinkero-linux-amd64
sudo mv tinkero-linux-amd64 /usr/local/bin/tinkero

# macOS (amd64)
wget https://github.com/yourusername/tinkero/releases/latest/download/tinkero-darwin-amd64
chmod +x tinkero-darwin-amd64
sudo mv tinkero-darwin-amd64 /usr/local/bin/tinkero

# macOS (arm64 - Apple Silicon)
wget https://github.com/yourusername/tinkero/releases/latest/download/tinkero-darwin-arm64
chmod +x tinkero-darwin-arm64
sudo mv tinkero-darwin-arm64 /usr/local/bin/tinkero

Build from Source

cd cmd/tinkero
go build -o tinkero .
sudo mv tinkero /usr/local/bin/

Verify Installation

tinkero --help

Commands Overview

Command Description
tinkero setup Interactive setup wizard for initial deployment
tinkero config Configure and validate GitHub App credentials
tinkero health Check health status of all services
tinkero cleanup [site] Remove old releases to free disk space

tinkero setup

Interactive setup wizard for initial Tinkero deployment.

Usage

tinkero setup

Description

The setup wizard validates prerequisites, collects configuration, generates the .env file, and starts all Docker services.

Process

Step Description
1. Prerequisites Validates Docker, ports, disk space
2. Configuration Collects required passwords
3. Generate .env Creates configuration file
4. Start Services Runs docker compose up -d
5. Next Steps Displays GitHub App setup instructions

Prerequisites Validated

Check Requirement
Docker Version 20.10+
Docker Daemon Running
Docker Compose 2.0+
Port 80 Available
Port 443 Available
Disk Space 10 GB minimum

Configuration Collected

Setting Description Default

Example Session

🚀 Starting Tinkero Setup Wizard

ℹ️  Step 1/5: Validating prerequisites...

=== Prerequisite Validation Results ===

✅ Docker Version Check
   Version: 24.0.7 (required: 20.10+)

✅ Docker Daemon Check
   Status: Running

✅ Docker Compose Check
   Version: 2.21.0 (required: 2.0+)

✅ Port Availability Check
   Port 80: Available
   Port 443: Available

✅ Disk Space Check
   Available: 45 GB at '/' (required: 10 GB)

✅ Tinkero Directory Check
   Found: docker-compose.yml

ℹ️  Step 2/5: Collecting configuration...

📝 Configuration Setup

🔗 GitHub App Configuration
ℹ️  GitHub App setup will be completed after initial deployment
✅ GitHub webhook secret generated

ℹ️  Step 3/5: Generating configuration file...
✅ .env file created successfully

ℹ️  Step 4/5: Starting Tinkero services...
⚠️  This may take several minutes on first run...
[+] Running 3/3
 ✔ Container caddy           Started
 ✔ Container redis           Started
 ✔ Container webhook-handler Started
✅ Services started successfully

ℹ️  Step 5/5: Setup complete!

======================================================================
✅ Tinkero Setup Complete!
======================================================================

📋 Next Steps:

1. 🔒 Create GitHub App
   - Go to: https://github.com/settings/apps/new
   - Set webhook URL: https://lair.nntin.xyz/tinkero/webhook
   - Set webhook secret: abc123...
   - Download private key and save to /srv/tinkero/github-app-key.pem

2. 🔍 Verify Services
   - Check status: docker compose ps
   - View logs: docker compose logs -f

======================================================================
✅ Setup completed successfully!
======================================================================

⚠️  IMPORTANT: Save your passwords securely!
⚠️  The .env file contains sensitive credentials.

Exit Codes

Code Meaning
0 Setup completed successfully
1 Setup failed (see error message)

Error Scenarios

Prerequisites not met: 

❌ Docker is not installed or not accessible.
   Solution: Install Docker from https://docs.docker.com/get-docker/

Weak password: 

❌ Password must be at least 8 characters long
❌ Password must contain at least one letter and one number

tinkero config

Configure and validate GitHub App credentials.

Usage

tinkero config

Description

Interactive wizard to set up GitHub App integration. Validates credentials by calling the GitHub API before saving.

Process

Step Description
1. Collect Prompts for App ID, private key, webhook secret
2. Validate Calls GitHub API to verify credentials
3. Update .env Saves validated credentials
4. Restart Restarts webhook-handler service

Required Information

Setting Description How to Find
App ID Numeric identifier GitHub App settings page
Private Key .pem file path Download from GitHub App
Webhook Secret Shared secret Configured in GitHub App

Example Session

🔧 GitHub App Configuration Wizard

ℹ️  This wizard will help you configure your GitHub App credentials.
ℹ️  You'll need your GitHub App ID, private key file, and webhook secret.

ℹ️  Step 1/4: Collecting GitHub App credentials...

📝 GitHub App Configuration

Enter GitHub App ID (numeric): 123456
✅ App ID: 123456

Enter path to GitHub App private key file (.pem): /srv/tinkero/github-app-key.pem
✅ Private key: /srv/tinkero/github-app-key.pem

Enter GitHub App webhook secret: abc123def456ghi789jkl012mno345pqr678
✅ Webhook secret configured

ℹ️  Step 2/4: Validating GitHub App credentials...
✅ Successfully validated GitHub App: My Tinkero App

ℹ️  Step 3/4: Updating configuration file...
✅ Configuration file updated successfully

ℹ️  Step 4/4: Restarting webhook-handler service...
ℹ️  Restarting webhook-handler container...
✅ Webhook handler restarted successfully

======================================================================
✅ GitHub App Configuration Complete!
======================================================================

📋 Configuration Summary:

  GitHub App Name:    My Tinkero App
  GitHub App Slug:    my-tinkero-app
  App ID:             123456
  Private Key:        /srv/tinkero/github-app-key.pem
  Webhook Secret:     abc1...678

🎯 Next Steps:

1. 📦 Configure Repository
   - Install the GitHub App on your repository
   - Go to: https://github.com/apps/my-tinkero-app/installations/new
   - Select repositories to enable

2. 🔧 Verify Webhook Delivery
   - Go to: https://github.com/settings/apps/my-tinkero-app
   - Check "Advanced" → "Recent Deliveries"
   - Verify webhooks are being delivered successfully

3. 🧪 Test Deployment
   - Push to your repository
   - Check webhook-handler logs: docker compose logs -f webhook-handler

======================================================================
✅ Your GitHub App is now configured and ready!
======================================================================

Exit Codes

Code Meaning
0 Configuration completed successfully
1 Configuration failed (see error message)

Error Scenarios

Authentication failed (401): 

❌ Authentication failed (401 Unauthorized)

Troubleshooting:
  1. Verify App ID is correct (found in GitHub App settings)
  2. Ensure private key matches the App ID
  3. Check if private key has been regenerated (old keys become invalid)
  4. Confirm App hasn't been deleted or suspended

GitHub App Settings: https://github.com/settings/apps

App not found (404): 

❌ GitHub App not found (404 Not Found)

Troubleshooting:
  1. Double-check the App ID: 123456
  2. Verify the App still exists in your GitHub account
  3. Confirm you have access to the App

GitHub App Settings: https://github.com/settings/apps

Private key error: 

❌ Failed to generate JWT token: failed to parse private key

Troubleshooting:
  1. Ensure private key file is valid (downloaded from GitHub)
  2. Check that private key is in PEM format
  3. Verify the key hasn't been regenerated in GitHub settings

Private key not found: 

❌ Private key file not found: /path/to/key.pem
   Solution: Ensure you've downloaded the private key from GitHub App settings

tinkero health

Check health status of all Tinkero services.

Usage

tinkero health

Description

Performs comprehensive health checks on all services: - Docker container status - Redis connectivity

Services Checked

Service Health Check
caddy Container running
redis Container running + PING test
webhook-handler Container running + health status

Example Output (All Healthy)

🏥 Tinkero Health Check

ℹ️  Checking Docker containers...
ℹ️  Checking Redis connectivity...
======================================================================
📊 Service Health Status
======================================================================

🐳 Docker Containers:

  ✅ caddy                HEALTHY
      Container ID: b2c3d4e5f6g7
      Status: Up 2 hours

  ✅ redis                HEALTHY
      Container ID: c3d4e5f6g7h8
      Status: Up 2 hours (healthy)

  ✅ webhook-handler      HEALTHY
      Container ID: d4e5f6g7h8i9
      Status: Up 2 hours (healthy)

🔴 Redis Connectivity:

  ✅ Redis                CONNECTED
      Endpoint: localhost:6379

======================================================================
✅ Overall Status: ALL SERVICES HEALTHY
======================================================================

Example Output (Unhealthy)

🏥 Tinkero Health Check

ℹ️  Checking Docker containers...
ℹ️  Checking Redis connectivity...
======================================================================
📊 Service Health Status
======================================================================

🐳 Docker Containers:

  ⚠️  webhook-handler     DEGRADED
      Container ID: d4e5f6g7h8i9
      Status: Up 5 minutes (unhealthy)
      Error: Container reports unhealthy status

  ❌ redis                UNHEALTHY
      Error: Container not found. Solution: Run 'docker compose up -d' to start services

🔴 Redis Connectivity:

  ❌ Redis                DISCONNECTED
      Error: Failed to connect to Redis: dial tcp [::1]:6379: connect: connection refused.
      Solution: Check if Redis container is running and port 6379 is accessible

======================================================================
❌ Overall Status: SOME SERVICES UNHEALTHY
======================================================================

Troubleshooting steps:
  1. Check container logs: docker compose logs -f [service-name]
  2. Restart services: docker compose restart
  3. Rebuild services: docker compose up -d --build
  4. Check Docker daemon: systemctl status docker

Exit Codes

Code Meaning
0 All services healthy
1 One or more services unhealthy

Automation Usage

# Use in scripts
if tinkero health; then
  echo "All services are running"
else
  echo "Some services need attention"
  # Send alert, restart services, etc.
fi

# Use in cron for monitoring
*/5 * * * * /usr/local/bin/tinkero health || /usr/local/bin/send-alert.sh

tinkero cleanup

Manage and clean up old site releases to free disk space.

Usage

# Interactive mode - select site from list
tinkero cleanup

# Direct site specification
tinkero cleanup <site-name>

Description

Lists releases for a site and allows selective or bulk deletion of old releases. The current (active) release cannot be deleted.

Process

Step Description
1. Select Site Choose site (or provide as argument)
2. Scan Releases List all releases with size and date
3. Select to Delete Choose releases to remove
4. Confirm Verify before deletion

Example Session (Interactive)

🧹 Tinkero Release Cleanup

ℹ️  Step 1/4: Selecting site...

📁 Available Sites:

  [1] my-app
  [2] docs-site
  [3] blog

Select site (1-3): 1
✅ Site: my-app

ℹ️  Step 2/4: Scanning releases...
✅ Found 5 releases

ℹ️  Step 3/4: Selecting releases to delete...

================================================================================
📦 Available Releases
================================================================================

#    Release                        Modified             Size            Status
--------------------------------------------------------------------------------
1    release-20240108-143022       2024-01-08 14:30:22  45.2 MiB       ✅ CURRENT
2    release-20240107-091533       2024-01-07 09:15:33  43.8 MiB
3    release-20240106-163045       2024-01-06 16:30:45  44.1 MiB
4    release-20240105-120332       2024-01-05 12:03:32  42.7 MiB
5    release-20240104-085511       2024-01-04 08:55:11  43.2 MiB
--------------------------------------------------------------------------------
Total: 5 releases, 219.0 MiB

⚠️  Note: Current release (marked with ✅) cannot be deleted

Enter release numbers to delete (comma-separated, e.g., 1,3,5) or 'all' for all old releases: all

ℹ️  Step 4/4: Confirming deletion...

================================================================================
🗑️  Releases to Delete
================================================================================

  • release-20240107-091533          (43.8 MiB)
  • release-20240106-163045          (44.1 MiB)
  • release-20240105-120332          (42.7 MiB)
  • release-20240104-085511          (43.2 MiB)

Total to delete: 4 releases, 173.8 MiB to be freed

Are you sure you want to delete these releases? (yes/no): yes

ℹ️  Deleting releases...
✅ Deleted release-20240107-091533
✅ Deleted release-20240106-163045
✅ Deleted release-20240105-120332
✅ Deleted release-20240104-085511

================================================================================
✅ Cleanup Complete!
================================================================================

📊 Summary:
  • Releases deleted:   4 / 4
  • Disk space freed:   173.8 MiB

Selection Options

Input Action
2,3,4 Delete specific releases
all Delete all non-current releases
(empty) Cancel

Exit Codes

Code Meaning
0 Cleanup completed (or cancelled)
1 Cleanup failed (see error message)

Error Scenarios

Site not found: 

❌ Site 'invalid-site' not found.
   Solution: Check available sites with 'tinkero cleanup' (no arguments)

No releases directory: 

❌ Releases directory not found for site 'mysite'.
   Solution: Ensure site has been deployed at least once

Only current release: 

⚠️  Only the current release exists. Cannot delete it.

Cannot delete current: 

❌ Cannot delete current release: release-20240108-143022

Exit Codes

All commands follow consistent exit code conventions:

Exit Code Meaning
0 Success
1 Failure (error occurred)

Example Usage in Scripts

#!/bin/bash

# Run health check
if ! tinkero health; then
  echo "Health check failed, attempting restart..."
  docker compose restart
  sleep 30

  if ! tinkero health; then
    echo "Services still unhealthy after restart"
    # Send alert
    exit 1
  fi
fi

echo "All services healthy"

Environment Variables

The CLI reads configuration from the .env file in the Tinkero project directory.

Required Variables

Variable Description
ACME_EMAIL Email for Let's Encrypt
GITHUB_APP_ID GitHub App ID
GITHUB_APP_PRIVATE_KEY_PATH Path to GitHub App private key
GITHUB_WEBHOOK_SECRET Webhook validation secret
REDIS_URL Redis connection URL

Optional Variables

Variable Description Default
CLOUDFLARE_DNS_API_TOKEN Cloudflare API token (none)

Project Root Detection

The CLI automatically finds the project root by looking for docker-compose.yml in:

  1. Current directory
  2. Parent directories (up to 5 levels)
  3. When run from cmd/tinkero, goes up 2 levels

See Also: - Setup Guide - Installation instructions - Operations Guide - Day-to-day operations - Troubleshooting - Common issues