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.

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

You can log in using either the portal URL or the API URL:

# Portal URL format
alpacon login https://alpacon.io/myworkspace
 
# API URL format
alpacon login myworkspace.us1.alpacon.io
 
# Self-hosted
alpacon login alpacon.example.com
 
# Login via API token
alpacon login myworkspace.us1.alpacon.io -t apikey1234

For cloud workspaces, 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, specify a new URL 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

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