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.

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

brew tap alpacax/alpacon
brew install alpacon-cli

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

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

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

💡 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

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

Signing 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 generated automatically 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 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.

Default behavior on re-login

When re-signing in, the previous workspace URL stored in config.json will be reused automatically.
To sign 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:

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