Table of contents

Configuration

Customize the Podstack CLI behavior and defaults.

Configuration File

The CLI configuration is stored at ~/.podstack/config.yaml:

# Authentication
auth:
  token: your_api_token
  expires: 2024-12-31T00:00:00Z

# Defaults
defaults:
  project: my-default-project
  output: table
  gpu_type: A100

# API settings
api:
  endpoint: https://api.podstack.ai
  timeout: 30

# CLI behavior
cli:
  color: true
  pager: less
  confirm: true

Config Commands

View Configuration

# Show all config
podstack config show

# Show specific value
podstack config get defaults.project

Set Configuration

# Set default project
podstack config set defaults.project my-project

# Set default output format
podstack config set defaults.output json

# Set default GPU type
podstack config set defaults.gpu_type A100

Reset Configuration

# Reset single value
podstack config unset defaults.project

# Reset all
podstack config reset

Default Values

Default Project

Set the default project for all commands:

podstack config set defaults.project my-project

# Or use project command
podstack project use my-project

Override per-command:

podstack pod list --project other-project

Default Output Format

podstack config set defaults.output json

Options: table, json, yaml, wide

Default GPU Type

podstack config set defaults.gpu_type A100

Environment Variables

Environment variables override config file values:

VariableDescription
PODSTACK_API_TOKENAPI authentication token
PODSTACK_PROJECTDefault project
PODSTACK_OUTPUTOutput format
PODSTACK_API_ENDPOINTAPI endpoint URL
PODSTACK_NO_COLORDisable colored output
PODSTACK_DEBUGEnable debug mode

Example:

export PODSTACK_API_TOKEN=your_token
export PODSTACK_PROJECT=my-project
export PODSTACK_OUTPUT=json

Output Formats

Table (Default)

podstack pod list --output table

NAME          STATUS    GPU       CREATED
my-pod        running   A100 x1   2024-01-15
training      stopped   H100 x2   2024-01-14

Wide

podstack pod list --output wide

Shows additional columns.

JSON

podstack pod list --output json

[
  {
    "id": "pod-123",
    "name": "my-pod",
    "status": "running",
    "gpu_type": "A100",
    "gpu_count": 1
  }
]

YAML

podstack pod list --output yaml

Quiet

IDs only, for scripting:

podstack pod list --quiet

pod-123
pod-456

Profiles

Manage multiple accounts or environments:

# ~/.podstack/config.yaml
profiles:
  default:
    auth:
      token: personal_token
    defaults:
      project: personal

  work:
    auth:
      token: work_token
    api:
      endpoint: https://api.work.podstack.ai
    defaults:
      project: work-project

  staging:
    auth:
      token: staging_token
    api:
      endpoint: https://api.staging.podstack.ai

Using Profiles

# Use specific profile
podstack --profile work pod list

# Set default profile
podstack config set-profile work

# Show current profile
podstack config get-profile

CLI Behavior

Disable Confirmation Prompts

podstack config set cli.confirm false

Or use --yes flag:

podstack pod delete my-pod --yes

Disable Colors

podstack config set cli.color false

# Or via environment
export PODSTACK_NO_COLOR=1

Custom Pager

podstack config set cli.pager "less -R"

Debug Mode

# Enable debug output
podstack --debug pod list

# Or via environment
export PODSTACK_DEBUG=1

API Configuration

Custom Endpoint

For enterprise or self-hosted:

podstack config set api.endpoint https://api.custom.podstack.ai

Timeout

podstack config set api.timeout 60  # seconds

Proxy

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

Aliases

Create command aliases in your shell:

# ~/.bashrc or ~/.zshrc

# Quick pod creation
alias newpod='podstack pod create --gpu-type A100 --wait'

# List running pods
alias pods='podstack pod list --status running'

# SSH to pod
psh() {
  podstack pod ssh "$1"
}

Shell Integration

Auto-completion

See Installation for shell completion setup.

Prompt Integration

Show current project in prompt:

# ~/.bashrc
PS1='$(podstack project current 2>/dev/null) \$ '

Troubleshooting

View Debug Info

podstack --debug config show

Check Config Location

podstack config path

Reset Everything

rm -rf ~/.podstack
podstack auth login

Next Steps