CLI Configuration

Configure the ShellHub CLI for CI/CD pipelines and automation workflows.

Prefer the dashboard? Most configuration can be done through the ShellHub Dashboard. CLI configuration is only needed for automation use cases.

// Configuration File

The ShellHub CLI uses a configuration file at ~/.shellhub/config.yaml:

# ~/.shellhub/config.yaml

# Default cloud for deployments
default_cloud: my-production-cloud

# Default region for new clouds
default_region: us-east-1

# Output format (text, json, yaml)
output_format: text

# Enable colored output
color: true

# API endpoint (for enterprise/self-hosted)
api_url: https://api.shellhub.app

# Timeout for API requests (seconds)
timeout: 30

# Enable debug logging
debug: false

# Editor for interactive commands
editor: vim

# Project-specific settings
projects:
  /path/to/my-project:
    cloud: staging-cloud
    region: eu-central-1

Configuration Options

Option	Default	Description
`default_cloud`	-	Cloud to use when --cloud flag is not specified
`default_region`	us-east-1	Region for new cloud creation
`output_format`	text	Output format: text, json, yaml
`color`	true	Enable/disable colored output
`timeout`	30	API request timeout in seconds
`debug`	false	Enable debug logging

// Environment Variables

Environment variables override configuration file settings:

Variable	Description
`SHELLHUB_API_KEY`	API key for authentication (skips login)
`SHELLHUB_API_URL`	API endpoint URL
`SHELLHUB_DEFAULT_CLOUD`	Default cloud name
`SHELLHUB_CONFIG_DIR`	Configuration directory (default: ~/.shellhub)
`SHELLHUB_NO_COLOR`	Disable colored output (set to 1)
`SHELLHUB_DEBUG`	Enable debug mode (set to 1)

# Example: Use in CI/CD
export SHELLHUB_API_KEY="ic_live_abc123..."
export SHELLHUB_DEFAULT_CLOUD="production"
shellhub deploy

// Project Configuration (shellhub.yaml)

Each project can have its own shellhub.yaml in the project root:

# shellhub.yaml - Project configuration
name: my-agent
version: 1.0.0
description: My awesome AI agent

# Runtime
runtime: python3.11
entrypoint: uvicorn main:app --host 0.0.0.0 --port 8000

# Resource allocation
resources:
  cpu: 2
  memory: 4Gi
  gpu: null  # or "nvidia-t4"

# Environment variables
env:
  LOG_LEVEL: info
  OPENAI_API_KEY: ${secrets.OPENAI_API_KEY}

# Health check
healthcheck:
  path: /health
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

# Auto-scaling (Pro+)
scaling:
  min: 1
  max: 10
  target_cpu: 70
  target_memory: 80

# Network
network:
  port: 8000
  protocol: http

# Build settings
build:
  dockerfile: ./Dockerfile  # or null for auto-detect
  context: .
  args:
    NODE_ENV: production

# Deployment hooks
hooks:
  pre_deploy: ./scripts/pre-deploy.sh
  post_deploy: ./scripts/post-deploy.sh

# Metadata
metadata:
  team: backend
  environment: production

// Multiple Profiles

Manage multiple accounts or environments with profiles:

# ~/.shellhub/config.yaml
profiles:
  default:
    api_key_ref: default
    default_cloud: production

  staging:
    api_key_ref: staging
    default_cloud: staging-cloud
    default_region: eu-central-1

  personal:
    api_key_ref: personal
    default_cloud: my-experiments

# Use a specific profile
shellhub --profile staging deploy

# Set profile for session
export SHELLHUB_PROFILE=staging
shellhub deploy

// Credentials Storage

Credentials are stored securely at ~/.shellhub/credentials:

macOS

Credentials are stored in the macOS Keychain for maximum security.

Linux

Credentials use the system keyring (libsecret) or encrypted file fallback.

Windows

Credentials are stored in Windows Credential Manager.

# View stored credentials (names only)
shellhub auth list

# Remove stored credentials
shellhub logout

# Clear all credentials
shellhub auth clear

// Shell Auto-completion

Enable tab completion for faster CLI usage:

Bash

# Add to ~/.bashrc
eval "$(shellhub completion bash)"

Zsh

# Add to ~/.zshrc
eval "$(shellhub completion zsh)"

Fish

shellhub completion fish > ~/.config/fish/completions/shellhub.fish

Configuration Troubleshooting

# View current configuration

shellhub config show

# Reset configuration to defaults

shellhub config reset

# Validate shellhub.yaml

shellhub validate