alpacon websh

Open a websh terminal for interacting with a server or execute a command directly on the server. Supports SSH-like user@host syntax for specifying the username inline.

alpacon websh [flags] [USER@]SERVER [COMMAND]

On Windows servers the shell is PowerShell, and commands run as SYSTEM regardless of the account or the --username/--groupname flags. See Windows servers.

Options

  -h, --help   help for websh

Flags

User and group control

• -u, --username [USER_NAME] - Specify the username under which the command should be executed
• -g, --groupname [GROUP_NAME] - Specify the group name under which the command should be executed

Environment variables

• --env="KEY=VALUE" - Set the environment variable ‘KEY’ to ‘VALUE’ for the command
• --env="KEY" - Use the current shell’s value for the environment variable ‘KEY’

Session sharing

• -s, --share - Share the current terminal to others via a temporary link
• --read-only=[true|false] - Set the shared session to read-only mode (default is false)

Work session

• --work-session [UUID] - Attach this session to a work-session (overrides the active session set via alpacon work-session use)

Note: All flags must be placed before the server name. Everything after the server name is treated as the remote command.

Examples

Open a websh terminal

Open a websh terminal for a server:

alpacon websh my-server

Open as root user:

alpacon websh root@my-server

Open with specific user and group:

alpacon websh admin@my-server
alpacon websh -u admin -g developers my-server

Execute commands

Execute a command directly on a server:

alpacon websh my-server "ls -la /var/log"

Run a command as a specific user:

alpacon websh root@my-server "systemctl status nginx"
alpacon websh -u admin -g developers my-server "docker ps"

Environment variables

Set environment variables for the command:

alpacon websh --env="KEY1=VALUE1" --env="KEY2=VALUE2" my-server "echo $KEY1"

Use current shell’s environment variable:

alpacon websh --env="HOME" my-server "echo $HOME"

Share terminal session

Share the current terminal:

alpacon websh --share my-server
alpacon websh --share --read-only=true my-server

Join an existing shared session:

alpacon websh join --url [SHARED_URL] --password [PASSWORD]

Attach to a work session

alpacon websh --work-session 11111111-2222-3333-4444-555555555555 my-server

Work session requirement

When you sign in with browser login, alpacon websh requires an active work session. An interactive terminal needs the websh scope; executing a command directly (alpacon websh my-server "command") needs the command scope. Token authentication (API token or service token) bypasses this requirement.

The session to attach is resolved from the --work-session flag, the ALPACON_WORK_SESSION environment variable, or the active session set with alpacon work-session use—in that order. When the gate denies the operation, websh exits with code 3; run with --output json to get a machine-readable diagnostic on stderr. See Gate errors for the error codes.

MFA authentication

When connecting as a system account (e.g., root@my-server), your workspace’s Authentication settings may require additional MFA verification.

In the CLI, the MFA flow works as follows:

1. The CLI displays an MFA authentication link
2. Open the link in your browser and complete MFA verification
3. The CLI automatically detects successful authentication and continues the operation

The MFA link expires after 3 minutes. If the link expires, retry the command to receive a new link.

$ alpacon websh root@my-server
MFA authentication required.
Please open the following URL in your browser to complete MFA authentication:

  https://app.alpacon.io/mfa/verify?token=abc123

Waiting for MFA authentication... (timeout: 3m0s)
MFA authentication successful.

MFA verification remains valid for the duration configured in workspace authentication settings. Individual users can adjust their own timeout within the workspace-defined range from security settings. Subsequent system account connections within this period will not require re-authentication.

API token ACLs

When passing commands directly to websh with an API token (e.g., alpacon websh my-server "command"), the token must have ACL rules for each command. Interactive websh sessions are not restricted by command ACLs.

# Allow the commands this token can run on servers
alpacon token acl command add --token=my-token --command="pm2 restart *"
alpacon token acl command add --token=my-token --command="systemctl status *"
alpacon token acl command add --token=my-token --command="git pull"

Without matching ACL rules, the command will be rejected. Use * as a wildcard to allow variable arguments (e.g., echo * matches echo "hello").

See Token ACL management for details on wildcard patterns.

Related commands