CLI Authentication & Identity

The Hubfly space CLI utilizes secure bearer token authentication. Tokens authorize all REST API calls, container deployments, log streams, and SSH sessions.

Authentication System Overview

When you execute any CLI operation, ensureAuth() inspects local storage at ~/.hubfly/config.json or checks the HUBFLY_TOKEN environment variable.

If no valid session is found in an interactive terminal, the CLI guides you through browser authentication or prompts for a Personal Access Token (PAT). In non-interactive environments, it raises an explicit authentication required error.

hubfly login

Authenticates your local terminal with your Hubfly space account.

Interactive Browser Login

In an interactive terminal, running hubfly login displays your authentication link:

Personal Access Tokens & Headless CI

For scripted environments or GitHub Actions where interactive prompts cannot run, pass your token directly with --token or set the HUBFLY_TOKEN environment variable:

GitHub Actions Example

name: Deploy App
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Hubfly space CLI
        run: curl -fsSL https://raw.githubusercontent.com/hubfly-space/hubfly-cli/main/install.sh | bash
      - name: Deploy
        env:
          HUBFLY_TOKEN: ${{ secrets.HUBFLY_TOKEN }}
        run: hubfly deploy --project my-api --region eu-west-1 --yes

hubfly whoami

Validates your stored token against GET /api/v1/auth/me and prints identity details:

hubfly logout

Removes the stored token from ~/.hubfly/config.json and terminates local CLI session state:

API Error Codes & Backend Trace IDs

When an API call returns an HTTP error code (for example 401, 403 or 500), the CLI parses the JSON error response and surfaces its request/error trace identifier when one is available:

Provide the trace ID (for example err_91f82b7c01a) to support. The CLI also maps common failures to exit codes so CI can distinguish authentication, conflict, timeout and usage errors.