Authentication

Overview

The Ubicloud CLI uses personal access tokens for authentication. All API requests require a valid token set in the UBI_TOKEN environment variable.

Creating a Personal Access Token

Log in to the Ubicloud Console
Navigate to Settings → Access Tokens
Click Create Token
Give your token a descriptive name (e.g., “CLI Access”)
Copy the token immediately - it won’t be shown again

Store your token securely. Anyone with access to your token can manage your Ubicloud resources.

Setting the Token

Temporary (Current Session)

Set the token for your current terminal session:

export UBI_TOKEN="your-token-here"

Permanent Configuration

Add the token to your shell profile for persistent authentication:

Bash
Zsh
Fish

echo 'export UBI_TOKEN="your-token-here"' >> ~/.bashrc
source ~/.bashrc

echo 'export UBI_TOKEN="your-token-here"' >> ~/.zshrc
source ~/.zshrc

echo 'set -x UBI_TOKEN "your-token-here"' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Replace your-token-here with your actual token.

Verify Authentication

Test that authentication is working:

ubi vm list

If authentication is successful, you’ll see your virtual machines (or an empty list). If the token is missing or invalid, you’ll see:

! Personal access token must be provided in UBI_TOKEN env variable for use

Token Management Best Practices

Security Recommendations

Use Separate Tokens for Different Purposes

Create different tokens for:

Development/testing environments
Production deployments
CI/CD pipelines
Different team members

This allows you to revoke specific tokens without affecting others.

Rotate Tokens Regularly

Periodically create new tokens and revoke old ones:

Create a new token
Update your configuration
Verify the new token works
Revoke the old token

Never Commit Tokens to Version Control

Add token files to .gitignore:

.gitignore

.env
.env.local
**/secrets/*

Use Environment Management Tools

For complex environments, consider using:

direnv for per-directory environments
Secret management tools like HashiCorp Vault
CI/CD secret storage (GitHub Secrets, GitLab CI/CD Variables)

Environment Variables

The CLI supports these environment variables:

UBI_TOKEN

string

required

Your personal access token for authentication.

export UBI_TOKEN="ubic_xxxxxxxxxxxxx"

UBI_URL

string

default:"https://api.ubicloud.com/cli"

API endpoint URL. Override for custom or development environments.

# Use a different API endpoint
export UBI_URL="https://api.eu.ubicloud.com/cli"

UBI_DEBUG

string

default:""

Enable debug output. Set to 1 to see detailed request/response information.

export UBI_DEBUG=1
ubi vm list

Debug output includes:

Command arguments sent to API
Executed commands with full arguments
Validation steps

Tool-Specific Overrides

The CLI allows you to override the paths to external tools:

UBI_SSH

string

default:"ssh"

Path to SSH executable.

export UBI_SSH="/usr/local/bin/ssh"

UBI_SCP

string

default:"scp"

Path to SCP executable.

export UBI_SCP="/usr/local/bin/scp"

UBI_SFTP

string

default:"sftp"

Path to SFTP executable.

export UBI_SFTP="/usr/local/bin/sftp"

UBI_PSQL

string

default:"psql"

Path to psql executable.

export UBI_PSQL="/usr/local/pgsql/bin/psql"

UBI_PG_DUMP

string

default:"pg_dump"

Path to pg_dump executable.

export UBI_PG_DUMP="/usr/local/pgsql/bin/pg_dump"

UBI_PG_DUMPALL

string

default:"pg_dumpall"

Path to pg_dumpall executable.

export UBI_PG_DUMPALL="/usr/local/pgsql/bin/pg_dumpall"

Using Multiple Accounts

To work with multiple Ubicloud accounts, use shell functions or aliases:

~/.bashrc

# Personal account
alias ubi-personal='UBI_TOKEN="personal-token" ubi'

# Work account
alias ubi-work='UBI_TOKEN="work-token" ubi'

Usage:

ubi-personal vm list
ubi-work pg list

Alternatively, use a shell function for more flexibility:

~/.bashrc

function ubi-with() {
  local env=$1
  shift
  UBI_TOKEN=$(cat ~/.ubi-tokens/$env) ubi "$@"
}

Usage:

ubi-with production vm list
ubi-with staging pg create ...

CI/CD Integration

For automated deployments, store the token as a secret:

GitHub Actions
GitLab CI
Jenkins

.github/workflows/deploy.yml

name: Deploy
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install CLI
        run: |
          curl -LO https://github.com/ubicloud/cli/releases/latest/download/ubi-linux-amd64
          chmod +x ubi-linux-amd64
          sudo mv ubi-linux-amd64 /usr/local/bin/ubi
      - name: Deploy
        env:
          UBI_TOKEN: ${{ secrets.UBI_TOKEN }}
        run: |
          ubi vm create ...

.gitlab-ci.yml

deploy:
  image: ubuntu:latest
  before_script:
    - apt-get update && apt-get install -y curl
    - curl -LO https://github.com/ubicloud/cli/releases/latest/download/ubi-linux-amd64
    - chmod +x ubi-linux-amd64
    - mv ubi-linux-amd64 /usr/local/bin/ubi
  script:
    - ubi vm create ...
  variables:
    UBI_TOKEN: $UBI_TOKEN

Jenkinsfile

pipeline {
  agent any
  environment {
    UBI_TOKEN = credentials('ubicloud-token')
  }
  stages {
    stage('Deploy') {
      steps {
        sh '''
          curl -LO https://github.com/ubicloud/cli/releases/latest/download/ubi-linux-amd64
          chmod +x ubi-linux-amd64
          sudo mv ubi-linux-amd64 /usr/local/bin/ubi
          ubi vm create ...
        '''
      }
    }
  }
}

Troubleshooting

Token Not Found

If you see “Personal access token must be provided”:

Verify the variable is set:
```
echo $UBI_TOKEN
```
Ensure there are no typos in the variable name
Check that your shell profile is loaded:
```
source ~/.bashrc  # or ~/.zshrc
```

Invalid Token

If you get authentication errors:

Verify the token hasn’t been revoked in the console

Check for extra whitespace or quotes:

# Wrong - includes quotes
export UBI_TOKEN='"token"'

# Correct
export UBI_TOKEN="token"

Generate a new token if needed

Token Exposed

If your token is accidentally exposed:

Immediately revoke it in the Ubicloud Console
Create a new token
Update all configurations using the old token
Review access logs for suspicious activity

Next Steps

CLI Overview

Learn about available commands

Virtual Machines

Create and manage VMs

Overview

Commands

Overview

Creating a Personal Access Token

Setting the Token

Temporary (Current Session)

Permanent Configuration

Verify Authentication

Token Management Best Practices

Security Recommendations

Environment Variables

Tool-Specific Overrides

Using Multiple Accounts

CI/CD Integration

Troubleshooting

Token Not Found

Invalid Token

Token Exposed

Next Steps

CLI Overview

Virtual Machines

Build docs developers (and LLMs) love

Overview

Commands

​Overview

​Creating a Personal Access Token

​Setting the Token

​Temporary (Current Session)

​Permanent Configuration

​Verify Authentication

​Token Management Best Practices

​Security Recommendations

​Environment Variables

​Tool-Specific Overrides

​Using Multiple Accounts

​CI/CD Integration

​Troubleshooting

​Token Not Found

​Invalid Token

​Token Exposed

​Next Steps

CLI Overview

Virtual Machines

Build docs developers (and LLMs) love

Overview

Creating a Personal Access Token

Setting the Token

Temporary (Current Session)

Permanent Configuration

Verify Authentication

Token Management Best Practices

Security Recommendations

Environment Variables

Tool-Specific Overrides

Using Multiple Accounts

CI/CD Integration

Troubleshooting

Token Not Found

Invalid Token

Token Exposed

Next Steps