Table of contents

Authentication

Configure the Podstack CLI to access your account.

Login Methods

Prompts for your API token directly in the terminal:

podstack auth login

This will:

  1. Show where to generate a token in the Podstack portal
  2. Prompt you to paste the token securely in your terminal
  3. Save credentials to your config (or keyring if enabled)

API Token Login

Use an API token for non-interactive environments:

podstack auth login --token YOUR_API_TOKEN

Generate a token at Account > API Tokens in the dashboard.

Environment Variable

Set the token as an environment variable:

# Linux/macOS
export PODSTACK_API_TOKEN=your_api_token

# Windows (PowerShell)
$env:PODSTACK_API_TOKEN = "your_api_token"

# Windows (CMD)
set PODSTACK_API_TOKEN=your_api_token

Verify Authentication

Check your authentication status:

podstack auth status

Output:

Authenticated as: [email protected]
Account ID: acc_123456
Token expires: 2024-12-31

View current user:

podstack auth whoami

Configuration File

The CLI stores credentials in ~/.podstack/config.yaml:

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

defaults:
  project: my-project
  output: table

Multiple Profiles

Configure multiple accounts:

profiles:
  default:
    token: personal_token
    project: personal-project

  work:
    token: work_token
    project: work-project
    api_endpoint: https://api.work.podstack.ai

Use a specific profile:

podstack --profile work pod list

Or set the default:

podstack config set-profile work

Project Context

Set the default project:

# Set default project
podstack project use my-project

# Or via environment variable
export PODSTACK_PROJECT=my-project

View current project:

podstack project current

Logout

Remove stored credentials:

podstack auth logout

This removes the token from the config file.

Token Management

View Token Info

podstack auth token-info

Refresh Token

podstack auth refresh

Revoke Token

Revoke the current token (requires re-authentication):

podstack auth revoke

CI/CD Integration

GitHub Actions

- name: Setup Podstack CLI
  run: |
    curl -sSL https://get.podstack.ai/cli | bash
    podstack auth login --token ${{ secrets.PODSTACK_API_TOKEN }}

- name: Deploy Pod
  run: podstack pod create --name ci-pod --image myimage:latest

GitLab CI

deploy:
  script:
    - curl -sSL https://get.podstack.ai/cli | bash
    - export PODSTACK_API_TOKEN=$PODSTACK_TOKEN
    - podstack pod create --name ci-pod --image myimage:latest

Jenkins

pipeline {
    environment {
        PODSTACK_API_TOKEN = credentials('podstack-token')
    }
    stages {
        stage('Deploy') {
            steps {
                sh 'podstack pod create --name ci-pod --image myimage:latest'
            }
        }
    }
}

Security Best Practices

  1. Use environment variables in CI/CD
  2. Never commit tokens to version control
  3. Rotate tokens regularly
  4. Use minimal permission tokens when possible
  5. Logout on shared machines

Secure Token Storage

On Linux, use a keyring:

# Store token securely
podstack auth login --use-keyring

On macOS, tokens are stored in Keychain by default.

Troubleshooting

Token Expired

Error: Token expired

Solution: Re-authenticate

podstack auth login

Invalid Token

Error: Invalid authentication token

Solution: Generate a new token from the dashboard

Permission Denied

Error: Permission denied for resource

Solution: Check if the token has access to the project

podstack project list

Next Steps