Getting Started with Alpacon CLI

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

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.

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

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

VERSION=<latest-version>
wget https://github.com/alpacanetworks/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 (opens in a new tab).

3. Login & Logout

To use all features of the Alpacon CLI, you must first authenticate with the Alpacon API.

Login

alpacon login [WORKSPACE_URL]  # e.g., alpacax.dev.alpacon.io

Logging in to https://alpacax.dev.alpacon.io

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

Please authenticate by visiting the following URL:
https://auth.dev.alpacon.io/activate?user_code=BBHT-GNKB  # Open this link in your browser to complete authentication

===============================================================

Logout

alpacon logout

config.json

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

~/.alpacon/config.json

This file includes:

• Workspace URL
• API token
• Token expiration time (valid for approximately one week)

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

If you run the alpacon logout command, this config.json file will be deleted, and you will need to log in again to continue using the CLI.

Default behavior on re-login

When re-logging in, the previous workspace URL stored in config.json will be reused automatically.
To log in to a different workspace, specify a new URL in the command.

4. List Registered Servers

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

alpacon server ls / list / all

5. Connect to Websh

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

Only servers in the CONNECTED state (true) can be accessed.

Basic Connection

alpacon websh [SERVER NAME]

Connect as root

You can also connect with root privileges:

alpacon websh -r [SERVER NAME]

Exit

exit