Authentication

Before you can deploy or manage projects, you need to authenticate with Hostess. The CLI supports interactive login for local development and token-based authentication for CI/CD pipelines.

Logging in

Run the login command to start the authentication flow:

Terminal

hostess login

The CLI only supports email + one-time password (OTP). There is no GitHub (or other OAuth) option in the terminal — use the email tied to your Hostess account. If you created your account via GitHub in Studio, use the same email address Studio has on file.

Hostess Studio offers GitHub sign-in in the browser. That is separate from hostess login, which always uses email and an OTP sent to your inbox.

Enter your email address

The CLI prompts for your email (new users complete first and last name next):

Login to Hostess

Enter your email address:
you@example.com

Check your inbox

Hostess sends a 6-digit code to your email.

Enter the verification code

Check your email!

Enter code:
482901

✓ Logged in as you@example.com

Your authentication token is saved locally and will be used for all subsequent CLI commands.

Checking your current session

To see which Hostess user your CLI token belongs to (from hostess login or a saved session):

Terminal

hostess whoami

The command prints a short summary with Email and Username only — it does not show the current organization or your role there. (Username may be empty if your account has no username set.)

Example (layout is a rounded bordered panel in the terminal; labels and values match the output):

┌──────────────────────────────────────────────────┐
│ Current User                                     │
│                                                  │
│ Email:      you@example.com                      │
│ Username:   janedoe                              │
└──────────────────────────────────────────────────┘

To see organization context, use hostess orgs list (current org is marked with ✓) or hostess orgs info.

Logging out

To clear your stored credentials and end your session:

Terminal

hostess logout

✓ Logged out successfully

This removes your authentication token from the local configuration file. You will need to run hostess login again to use the CLI.

Token storage

Hostess stores your authentication token in a local configuration file at:

~/.hostess/config.json

This file stores your session token (and optional organization context). An example of the file structure:

~/.hostess/config.json

{
  "token": "hst_abc123..."
}

Keep your config file secure

The config.json file contains your authentication token. Do not share this file, commit it to version control, or expose it in logs. Treat it like a password.

CI/CD authentication

For automated pipelines (GitHub Actions, GitLab CI, etc.), you do not want to use interactive login. Instead, use a Personal Access Token (PAT) or a CI/CD token.

Creating a token

Create a Personal Access Token in Hostess Studio: open your account or organization settings and use the Personal Access Tokens section. Copy the token once — it is not shown again — and store it in your CI provider’s secret store (for example HOSTESS_TOKEN in GitHub Actions).

Using a token

There are two ways to pass a token to the CLI in non-interactive environments:

Set the HOSTESS_TOKEN environment variable. This is the recommended approach for CI/CD:

Terminal

export HOSTESS_TOKEN=hst_ci_abc123...
hostess deploy

In GitHub Actions:

.github/workflows/deploy.yml

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Hostess CLI
        uses: howl-cloud/setup-hostess@v1
      - name: Deploy
        env:
          HOSTESS_TOKEN: ${{ secrets.HOSTESS_TOKEN }}
        run: hostess deploy --no-interactive

Pass the token directly with the --token flag:

Terminal

hostess deploy --token hst_ci_abc123...

Passing tokens via command-line flags can expose them in shell history and process listings. Prefer the environment variable approach for CI/CD.

Auth resolution order

When you run a CLI command, Hostess resolves your authentication token in the following order:

Priority	Source	Description
1 (highest)	`--token` flag	Token passed directly on the command line
2	`HOSTESS_TOKEN` env var	Token set as an environment variable
3 (lowest)	`~/.hostess/config.json`	Token stored from `hostess login`

The first token found is used. If no token is found at any level, the CLI will prompt you to log in (or fail with an error in non-interactive mode).

Token security best practices

Never commit tokens to your repository. Use your CI/CD platform's secret management (e.g., GitHub Secrets, GitLab CI Variables).
Rotate tokens regularly and revoke any tokens you no longer need.
Use scoped tokens for CI/CD rather than your personal login token.
Add ~/.hostess/ to your global .gitignore to prevent accidental commits.

Next steps

Now that you are authenticated, follow the Quick Start to deploy your first application.

On this page