---
title: "Run your first command with the CLI"
description: "Install the Alpacon CLI, sign in, request a bounded work session, and run a safe command on a registered server. Then inspect your session and complete it."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Run your first command with the CLI

<span id="getting-started" />
# Run your first command with the CLI

**Alpacon CLI** lets you work with Alpacon from your terminal. This tutorial installs the CLI, signs in, requests a work session, runs `whoami`, and completes the session. Use a server that you are allowed to access.

## 1. Prerequisites

Make sure the following conditions are met:

- A workspace invitation and a registered server whose agent is online. See [Install Alpamon](/use/servers/register/install/) if your server is not registered yet.

## 2. Installation

Alpacon CLI can be installed in various ways depending on your operating system. Select the appropriate tab below to proceed.

**Want an AI assistant to do this?** Copy the prompt below into Claude, Cursor, or another AI tool. An assistant running on your machine (like Claude Code) can detect your OS and run the steps; in a chat, just tell it your OS.

```text
Install the Alpacon CLI on my machine. Detect my OS (Linux, macOS, or Windows), or use the OS I tell you, then follow https://docs.alpacax.com/learn/tutorials/cli/ and run the matching install steps. Verify the result with `alpacon version`.
```

  
    #### Ubuntu / Debian

    ```bash
    curl -s https://packagecloud.io/install/repositories/alpacax/alpacon/script.deb.sh?any=true | sudo bash
    sudo apt-get install alpacon
    ```

    #### CentOS / RHEL

    ```bash
    curl -s https://packagecloud.io/install/repositories/alpacax/alpacon/script.rpm.sh?any=true | sudo bash
    sudo yum install alpacon
    ```

    #### GitHub releases

    ```bash
    VERSION=<latest-version>
    wget https://github.com/alpacax/alpacon-cli/releases/download/${VERSION}/alpacon-${VERSION}-linux-amd64.tar.gz
    tar -xvf alpacon-${VERSION}-linux-amd64.tar.gz
    chmod +x alpacon
    sudo mv alpacon /usr/local/bin
    ```

  

  
    #### Homebrew

    ```bash
    brew install alpacax/alpacon/alpacon-cli
    ```

    #### GitHub Releases

    ```bash
    VERSION=<latest-version>
    wget https://github.com/alpacax/alpacon-cli/releases/download/${VERSION}/alpacon-${VERSION}-darwin-arm64.tar.gz
    tar -xvf alpacon-${VERSION}-darwin-arm64.tar.gz
    chmod +x alpacon
    sudo mv alpacon /usr/local/bin
    ```

  

  
    If you're using Docker, you can run the CLI without installation:

    ```bash
    docker run --rm -it alpacax/alpacon-cli version
    ```

  

  
    Requires Go to be installed:

    ```bash
    git clone https://github.com/alpacax/alpacon-cli.git
    cd alpacon-cli
    go build
    sudo mv alpacon-cli /usr/local/bin/alpacon
    ```

  

  
    #### GitHub Releases

    Download the latest Windows build, extract it, and add it to your `PATH`. In **PowerShell**:

    ```powershell
    # Pick the version from the Releases page (use windows-arm64 on ARM devices)
    $Version = "<latest-version>"
    $Dest = "$env:LOCALAPPDATA\Alpacon"

    Invoke-WebRequest -UseBasicParsing `
      -Uri "https://github.com/alpacax/alpacon-cli/releases/download/$Version/alpacon-$Version-windows-amd64.zip" `
      -OutFile "$env:TEMP\alpacon.zip"
    Expand-Archive -Path "$env:TEMP\alpacon.zip" -DestinationPath $Dest -Force

    # Add alpacon to your PATH (current user)
    [Environment]::SetEnvironmentVariable(
      "Path", "$([Environment]::GetEnvironmentVariable('Path','User'));$Dest", "User")
    ```

    Open a **new** terminal (PowerShell or Windows Terminal) so the updated `PATH` takes effect, then verify:

    ```powershell
    alpacon version
    ```

    All commands work the same as on Linux and macOS. Your login config is stored at `%USERPROFILE%\.alpacon\config.json`.
  

---

For the latest installation instructions, refer to the [official GitHub repository](https://github.com/alpacax/alpacon-cli).

## 3. Login & logout

To use all features of the Alpacon CLI, authentication with the Alpacon API is required.

### Login

For **Alpacon Cloud**, log in with your workspace name and region, or run `alpacon login` with no arguments to be prompted interactively. For **self-hosted**, pass your host as the argument:

```bash
# Alpacon Cloud (interactive)
alpacon login

# Alpacon Cloud (non-interactive)
alpacon login --workspace myworkspace --region us1

# Alpacon Cloud with an API token
alpacon login --workspace myworkspace --region us1 -t apikey1234

# Self-hosted
alpacon login alpacon.example.com
```

For Alpacon Cloud browser login (without an API token), authentication is handled via the browser. The CLI will display a URL to open:

```
Logging in to https://myworkspace.us1.alpacon.io

==================== AUTHENTICATION REQUIRED ====================

Please authenticate by visiting the following URL:
https://auth.alpacon.io/activate?user_code=BBHT-GNKB

===============================================================
```

Open the link in your browser to complete authentication (including MFA if required by your workspace).

### Re-login

When re-logging in, the **previous workspace URL** stored in `config.json` will be reused automatically:

```bash
alpacon login  # Uses saved workspace URL
```

To sign in to a different workspace, pass `--workspace` and `--region` (Alpacon Cloud) or a new host (self-hosted) in the command.

### Workspace management

If you logged in via Auth0, you can list and switch between workspaces without re-authenticating:

```bash
# View current workspace
alpacon workspace

# List all available workspaces
alpacon workspace ls

# Switch to a different workspace
alpacon workspace switch other-workspace
```

Workspace switching works across regions (e.g., from `us1` to `ap1`). The workspace list is extracted from your login token—no additional API calls are required.

### Logout

```bash
alpacon logout
```

> If you are in multi-workspace mode, logging out will end the session for **all workspaces** associated with your account.

### config.json

After successful login, a configuration file is generated automatically at:

```
~/.alpacon/config.json              # Linux and macOS
%USERPROFILE%\.alpacon\config.json  # Windows
```

This file includes:

- Workspace URL and name
- Authentication tokens
- Base domain (for multi-workspace support)

This file is essential for executing CLI commands. If the token expires, you must sign in again.

_If you run the `alpacon logout` command, this `config.json` file will be removed, and you will need to sign in again to continue using the CLI._

## 4. List registered servers

To view the list of servers registered in your workspace, run the following command:

```bash
alpacon server ls
alpacon server list
```

## 5. Create a work session

When you sign in with browser login, access commands such as `websh`, `exec`, `cp`, and `tunnel` require an active [work session](/reference/cli/work-session/). The token exception covers only non-interactive `exec`, `cp`, `edit`, and `websh SERVER "command"`. Tokens cannot open interactive Websh or tunnels; use `alpacon login` without `-t` for those operations.

New personal API tokens cannot hold command-execution or file-transfer scopes. Existing tokens with those scopes keep working without a work session. Use a [service token](/use/iam/applications/service-tokens/) for automation and CI.

Check whether your authentication requires a work session:

```bash
alpacon whoami
```

If it does, create a session, wait for approval, and set it as your active session in one step:

```bash
alpacon work-session create --purpose "server check" --scope command,websh \
  --server my-server --expires-in 1h --wait --use
```

Subsequent access commands attach to this session automatically. See the [`alpacon work-session`](/reference/cli/work-session/) reference for the full workflow.

## 6. Run and inspect a command

Run a harmless command on the server you selected. The active work session is attached automatically:

```bash
alpacon exec my-server -- whoami
```

Check the command result and review the session in [Session history](/use/audit/sessions/).

<span id="6-connect-to-websh" />

## 7. Connect to Websh

To access a server’s Websh terminal, use the following command:

You can only access servers that are in a `CONNECTED` state. 

### Basic connection

```bash
alpacon websh my-server
```

### Connect as root

If your workspace permits direct root access and your request includes the account, you can connect as **root**:

```bash
alpacon websh root@my-server
```

### Exit

```bash
exit   # Close the current Websh session
```

When your task is done, complete the work session using the ID printed when you created it:

```bash
alpacon work-session complete SESSION_ID
```

## Learn more

You've now learned the basics of using the Alpacon CLI.  
Take full advantage of Alpacon by exploring its wide range of powerful CLI commands.

> For more details, visit the [Full CLI Command Reference](/reference/cli/).

Source: https://docs.alpacax.com/learn/tutorials/cli/