Getting started

Alpacon CLI is a command-line tool that allows you to manage Alpacon services from your terminal. This guide walks you through installation, server registration, and connecting to the Websh terminal.

1. Prerequisites

Make sure the following conditions are met:

  • Alpacon Server is running
  • Alpamon Agent is installed and running on the Alpacon Server

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.

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/reference/cli/getting-started/ and run the matching install steps. Verify the result with `alpacon version`.

Ubuntu / Debian

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

CentOS / RHEL

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

GitHub releases

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

đź’ˇ For the latest installation instructions, refer to the official GitHub repository.

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:

# 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:

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:

# 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

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:

alpacon server ls / 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. Token authentication (API token) bypasses this requirement.

Check whether your authentication requires a work session:

alpacon whoami

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

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

Subsequent access commands attach to this session automatically. See the alpacon work-session reference for the full workflow.

6. 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

alpacon websh [SERVER NAME]

Connect as root

You can also connect with root privileges:

alpacon websh root@[SERVER NAME]

Exit

exit   # Close the current Websh session

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.

Last updated: