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

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

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 install alpacax/alpacon/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

# 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")

alpacon version

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
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. 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 for automation and CI.

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 command,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. Run and inspect a command#

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

alpacon exec my-server -- whoami

Check the command result and review the session in Session history.

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#

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:

alpacon websh root@my-server

Exit#

exit   # Close the current Websh session

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

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.