HomeUse Cases

Guepard / Features / Guepard CLI

Guepard CLI Authentication

Secure Zero-Trust Access for Database Management

Guepard CLI implements a secure authentication workflow that combines browser-verified token issuance with cryptographically signed tokens, ensuring secure access while maintaining enterprise-grade audit capabilities. This feature is essential for developers and DevOps teams managing sensitive database environments through automated workflows.

Secure Authentication Architecture

Guepard CLI authentication provides multiple layers of security while maintaining developer productivity:

Core Security Components

  • Browser-Verified Issuance: Requires human approval through web interface
  • Scoped Permissions: Granular access controls for CLI operations
  • Immutable Audit Trails: Tamper-proof logs for compliance
  • Real-Time Revocation: Instant token invalidation across all systems
  • Local Token Storage: Secure credential management on your machine

Key Features

1. Interactive Authentication Workflow

The recommended authentication method uses a browser-verified process:

# Initiate authentication flow
guepard login

Step-by-step process:

$ guepard login
🐆 Starting login process...
✅ Login URL generated successfully!
🔗 URL: https://guepard.run/auth/login?code=abc123def456
Press Enter to open the login page in your browser... 

# After pressing Enter, your browser opens to the login page
# Complete the login process in your browser
# Then return to the terminal

Enter the verification code from the webpage: 123456
🐆 Completing login...
✅ Login successful. Happy coding! 🐆
You can now use the Guepard CLI to interact with your Guepard account.🐆
💡 To get started, run: `guepard --help`

2. Direct Token Authentication

For CI/CD systems and automated workflows, you can authenticate directly with a token:

guepard login --code your-access-token-here

Example:

guepard login --code eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. Browser Configuration Process

After initiating authentication with guepard login, the browser workflow includes:

  1. Open the generated URL in your browser
  2. Complete web authentication with your Guepard account
  3. Configure token settings (scopes, expiration, name)
  4. Receive verification code from the web interface
  5. Enter verification code in the CLI terminal

Token Management

Token Storage

Authentication tokens are stored securely on your local machine:

  • macOS: ~/Library/Application Support/guepard/token
  • Linux: ~/.config/guepard/token
  • Windows: %APPDATA%\guepard\token

Token Security

  • Tokens are stored in plain text files (consider using keyring integration for enhanced security)
  • Tokens have configurable expiration dates
  • Never share your tokens with others
  • Use environment variables for CI/CD systems
  • Tokens can be revoked instantly through the web interface

Token Refresh

Tokens automatically refresh when they expire. If you encounter authentication errors:

  1. Try running guepard login again
  2. Check your internet connection
  3. Verify your Guepard account is active
  4. Check if the token has been revoked

Checking Authentication Status

Verify Login Status

Check if you're currently authenticated by running any command that requires authentication:

# Try any command that requires authentication
guepard list deployments

If you're not authenticated, you'll see:

❌ Authentication required. Please run 'guepard login' first.

View Account Information

Once authenticated, you can view your account details:

guepard usage

This shows your current usage and quotas:

✅ Usage Summary:
┌─────────────┬───────┬──────┐
│ Resource    │ Quota │ Used │
├─────────────┼───────┼──────┤
│ Deployments │ 10    │ 3    │
│ Snapshots   │ 100   │ 15   │
│ Clones      │ 50    │ 8    │
└─────────────┴───────┴──────┘

Logging Out

Sign Out

To log out and clear your stored credentials:

guepard logout

Example output:

$ guepard logout
✅ Logged out successfully! 🐆

Verify Logout

After logging out, commands requiring authentication will fail:

$ guepard list deployments
❌ Authentication required. Please run 'guepard login' first.

Troubleshooting Authentication

Common Issues

"Authentication required" Error

❌ Authentication required. Please run 'guepard login' first.

Solution:

guepard login

"Invalid token" Error

❌ Invalid or expired token. Please run 'guepard login' again.

Solution:

guepard logout
guepard login

Browser Doesn't Open

If the browser doesn't open automatically:

  1. Copy the URL from the terminal
  2. Paste it into your browser manually
  3. Complete the login process
  4. Enter the verification code

Network Issues

If you encounter network-related errors:

  1. Check your internet connection
  2. Verify firewall settings
  3. Try using a different network
  4. Check if Guepard services are accessible

Manual Token Management

View Stored Token

# macOS/Linux
cat ~/.config/guepard/token

# Windows
type %APPDATA%\guepard\token

Clear Stored Token

# macOS/Linux
rm ~/.config/guepard/token

# Windows
del %APPDATA%\guepard\token

Set Token via Environment Variable

# Set environment variable
export GUEPARD_API_TOKEN="your-token-here"

# Use the token
guepard login --code $GUEPARD_API_TOKEN

CI/CD Integration

GitHub Actions

For automated deployments, use environment variables:

name: Deploy to Guepard
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Guepard CLI
        run: |
          wget https://github.com/Guepard-Corp/guepard-cli/releases/download/v0.27.14/guepard-cli-0.27.14-linux-amd64.tar.gz
          tar -xzf guepard-cli-0.27.14-linux-amd64.tar.gz
          sudo mv guepard /usr/local/bin/
      
      - name: Authenticate with Guepard
        run: guepard login --code ${{ secrets.GUEPARD_API_TOKEN }}
        env:
          GUEPARD_API_TOKEN: ${{ secrets.GUEPARD_API_TOKEN }}
      
      - name: Deploy
        run: guepard deploy --interactive

Docker Integration

The CLI can be used in Docker containers with proper token management:

FROM ubuntu:24.04

ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y build-essential procps curl file git

RUN useradd -ms /bin/bash linuxbrew
USER linuxbrew
WORKDIR /home/linuxbrew

# Install Guepard CLI
RUN /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" && \
    eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" && \
    brew tap guepard-corp/guepard && \
    brew install guepard

USER root
ENTRYPOINT ["/home/linuxbrew/.linuxbrew/bin/guepard"]

Other CI/CD Systems

For other CI/CD systems, follow the same pattern:

  1. Install Guepard CLI
  2. Set the GUEPARD_API_TOKEN environment variable
  3. Run guepard login --code $GUEPARD_API_TOKEN
  4. Execute your deployment commands

Security Best Practices

Token Security

  • Never commit tokens to version control
  • Use environment variables for CI/CD
  • Rotate tokens regularly if possible
  • Monitor token usage in your Guepard account
  • Use least-privilege scopes for your use case

Account Security

  • Use strong passwords for your Guepard account
  • Enable two-factor authentication if available
  • Monitor account activity regularly
  • Log out from shared machines
  • Use separate tokens for different environments

Network Security

  • Use HTTPS for all Guepard communications
  • Verify SSL certificates in corporate environments
  • Use VPN if required by your organization
  • Check firewall rules for Guepard domains
  • Monitor network traffic for suspicious activity

Account Management

Creating a Guepard Account

If you don't have a Guepard account:

  1. Visit guepard.run
  2. Click "Sign Up" or "Get Started"
  3. Complete the registration process
  4. Verify your email address
  5. Start using Guepard CLI

Account Limits

Free accounts include:

  • Limited number of deployments
  • Limited snapshots
  • Limited clones/branches

Upgrade your account for:

  • More deployments
  • Higher quotas
  • Priority support
  • Advanced features

Token Scopes and Permissions

Tokens can be configured with specific scopes:

  • admin: Full access to all operations
  • read: Read-only access to deployments and data
  • write: Create and modify deployments
  • compute: Manage compute instances
  • deploy: Deploy and manage database instances

Enterprise Features

Centralized Management

  • View active tokens across teams
  • Revoke individual or all tokens instantly
  • Audit historical token usage
  • Set organization-wide policies

RBAC Integration

  • Assign roles and permissions to users
  • Fine-grained access control for CLI operations
  • Team-based access management
  • Integration with enterprise identity providers

Usage Analytics

  • Monitor CLI adoption across teams
  • Track usage patterns and optimization opportunities
  • Identify areas for improvement
  • Generate compliance reports

Compliance Alignment

  • GDPR compliance with data handling
  • HIPAA compliance for healthcare data
  • SOC 2 compliance for security standards
  • Audit trail maintenance for regulatory requirements

Support and Resources

Getting Help

If you encounter authentication issues:

  1. Check this guide for common solutions
  2. Join our Discord community for help
  3. Create a GitHub issue for bugs
  4. Contact support for account-specific issues

Documentation Resources

Why Choose Guepard CLI Authentication?

Unlock Secure Automation with Guepard CLI

Guepard CLI empowers developers and DevOps teams with secure, intuitive authentication for modern database automation. Its browser-verified token issuance, streamlined workflows, and real-time token management simplify complex operations while ensuring enterprise-grade security.

Key Benefits

  • 🔒 Browser-verified token issuance for enhanced security
  • 🛡️ Scope-limited access for all operations
  • 📜 Immutable audit trails for compliance
  • ⚡ Instant revocation with global token invalidation
  • 🚀 Developer-friendly authentication flow
  • 🏢 Enterprise-ready with centralized management
Previous
CLI Commands
Next
Self Service Portal