> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.vessl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# vesslctl config, auth, billing & utility

> Configure the CLI, manage authentication, check billing, and update vesslctl.

These commands handle CLI configuration, authentication, account billing, and utility operations.

## Config commands

### config show

Display the current CLI configuration, including the config file path, authentication status, and resolved context (organization, team, API URL) with their sources.

```bash theme={null}
vesslctl config show
```

**Example output:**

```text theme={null}
Config File:       ~/.config/vesslctl/config.yaml
Auth Status:       logged in

default_org (config):    vessl-ai
default_team (config):   ml-research
API URL (resolved):      https://api.cloud.vessl.ai (from default)
Output (resolved):       table (from default)
Org (resolved):          vessl-ai (from config)
Team (resolved):         ml-research (from config)
```

### config set

Set a configuration value.

```bash theme={null}
vesslctl config set <key> <value>
```

| Key             | Description                               |
| --------------- | ----------------------------------------- |
| `default_org`   | Default organization for all commands     |
| `default_team`  | Default team for all commands             |
| `output_format` | Output format (`table`, `json`, or `csv`) |
| `api_url`       | VESSL Cloud API endpoint URL              |

**Example:**

```bash theme={null}
vesslctl config set output_format json
vesslctl config set default_org vessl-ai
```

## Auth commands

### auth login

Authenticate with VESSL Cloud. The default flow opens a browser for OAuth and falls back to email and password if the browser is unavailable.

```bash theme={null}
vesslctl auth login
```

| Flag         | Short | Description                                            |
| ------------ | ----- | ------------------------------------------------------ |
| `--web`      |       | Use browser OAuth only — disable the password fallback |
| `--password` |       | Use email and password login instead of browser OAuth  |

**Example:**

```bash theme={null}
# Default browser OAuth (with password fallback)
vesslctl auth login

# Password-based login
vesslctl auth login --password
```

<Note>
  **Inside a VESSL Cloud workspace.** When `VESSLCTL_ACCESS_TOKEN` or `SIDECAR_INITIAL_ACCESS_TOKEN` is set, `vesslctl auth login` is a no-op — the CLI uses the workload token directly and prints a notice instead. Pass `--web` or `--password` to override and start a fresh interactive login.
</Note>

### auth logout

Remove saved credentials from the local machine.

```bash theme={null}
vesslctl auth logout
```

### auth status

Display your current authentication status, including username, email, token validity, org/team context, and organization list.

```bash theme={null}
vesslctl auth status
```

**Example output:**

```text theme={null}
Username:       wayne
Email:          wayne@vessl.ai
Token:          Valid (expires 2026-05-01)
Organization:   vessl-ai
Team:           ml-research

ORGANIZATIONS
  vessl-ai (current)
  personal
```

## Billing command

### billing show

Display your current credit balance, burn rate, and estimated remaining hours.

```bash theme={null}
vesslctl billing show
```

## Utility commands

### version

Print the vesslctl version.

```bash theme={null}
vesslctl version
```

You can also use the `--version` flag on the root command:

```bash theme={null}
vesslctl --version
```

### install

Copy the current vesslctl binary to a directory in your PATH for permanent use. Useful after downloading vesslctl for the first time through the install script.

```bash theme={null}
vesslctl install
```

| Flag    | Description                                                    |
| ------- | -------------------------------------------------------------- |
| `--dir` | Target directory (default: `/usr/local/bin` or `~/.local/bin`) |

**Example:**

```bash theme={null}
# Install to default location
vesslctl install

# Install to a custom directory
vesslctl install --dir ~/bin
```

<Note>
  If the default directory requires root access, use `sudo vesslctl install`.
</Note>