Skip to main content

Using the CLI

Soln CLI is the command-line interface for signing in to Soln from a terminal.

Use it to authenticate with a tenant member account, verify the current session, and sign out.

Install​

Install the CLI from npm:

npm install -g @soln/cli

After installation, the command name is:

soln

Check the installed command:

soln help

Check the Version​

soln version

Prints the package name and the installed version, for example @soln/cli 0.1.0. soln --version, soln -v, and soln -V print the same value, and soln version --json returns {"name":"@soln/cli","version":"..."} for scripts.

Report this version when you ask for support, or compare it with the CLI release the Control Plane expects.

Login​

Use a tenant member account and password.

soln login --base-url <api-url> \
  --tenant <tenant-subdomain> \
  --email <email>

--tenant is the tenant subdomain, not the tenant UUID.

If the password is entered incorrectly, the CLI prompts again in the same command. After 3 failed password attempts, the command exits.

To log in with an email verification code:

soln login --base-url <api-url> \
  --tenant <tenant-subdomain> \
  --email <email> \
  --method email

The CLI sends a verification code to the member email address and prompts for the code in the terminal.

If the code is entered incorrectly, the CLI keeps prompting in the same command so the current verification code can still be used until it expires or reaches the server-side attempt limit.

If the account requires tenant selection or password setup, finish that flow in Soln Web first, then run soln login again.

Check Current Session​

soln whoami

This command verifies the locally stored session with Soln and prints the current member and tenant.

Use JSON output when calling from scripts or AI agents:

soln whoami --json

Example JSON shape:

{
  "authenticated": true,
  "callerType": "member",
  "email": "user@example.com",
  "tenant": {
    "id": "tenant-id",
    "subdomain": "acme",
    "type": "customer"
  },
  "expiresAt": "2026-05-28T12:00:00.000Z"
}

Logout​

soln logout

After the server confirms logout, the local token is removed.

Deployment Commands​

soln and sl are two names for the same CLI. A first installation uses deployment login → register → prepare → install. Follow Single-Machine Installation or External Services.

soln login authenticates everyday Runtime operations. sl deployment login authorizes Control Plane deployment management; these are separate sessions. Deployment authorization requires a tenant member with tenant.runtime.deployment.manage.

Deployment Login, Registration Status, and Logout​

sl deployment login --base-url <control-plane-api-url> \
  --tenant <tenant-subdomain> --email <member-email> --method email
sl deployment status --json
sl deployment logout

Enter the email code interactively; omit --method email for password login. The deployment session is stored at ~/.soln/deployment-session.json with mode 0600; do not share it. deployment status inspects the Control Plane registration, whereas sl status --dir ... inspects the local installation.

First Registration and Deployment Files​

sl deployment register --dir /opt/soln-tenant-runtime \
  --deployment-target server --deployment-mode singleMachine \
  --runtime-origin https://runtime.example.com
sl deployment prepare --dir /opt/soln-tenant-runtime

Use --deployment-mode externalServices when registering an external-services installation. Local deployments use --deployment-target local and only support singleMachine. Registration writes .soln-install-setup.json containing the Agent secret; deployment prepare uses it and the Control Plane registration to generate files. Do not share the setup file.

Do not repeat an existing registration. register --force replaces the Agent credential and is only for an intentional replacement. Resume an unfinished installation with its original directory and setup file; upgrade installed deployments. Do not overwrite an existing deployment with prepare --force.

Install and Check​

Configure .env.example (or .env for external services), then run:

sl install --dir /opt/soln-tenant-runtime \
  --setup-file /opt/soln-tenant-runtime/.soln-install-setup.json --yes
sl doctor --dir /opt/soln-tenant-runtime --json
sl status --dir /opt/soln-tenant-runtime --check --json

install populates identity and internal secrets, runs doctor, verifies the release, migrates the database, and starts Runtime. A manual doctor before first installation may report internal secrets that have not yet been generated; do not bypass checks with example secrets. After success, delete the one-time setup file and run sl deployment logout. Keep .env and .soln/deployment.json.

Lifecycle commands install, doctor, status, upgrade, and rollback accept --dir and default to the current directory. Registration, deployment file preparation, and domain changes require an explicit --dir. Deployment login, registration status, and logout do not use that option.

Upgrade and Rollback​

sl upgrade --dir /opt/soln-tenant-runtime --check
sl upgrade --dir /opt/soln-tenant-runtime --yes
sl rollback --dir /opt/soln-tenant-runtime

Upgrade backs up PostgreSQL. A normal rollback overwrites the database with that backup, discarding subsequent writes; it does not restore object storage or Temporal state. Keep rollback confirmation interactive. See Server Upgrade and Rollback.

Change the Access Domain​

sl deployment origin --dir /opt/soln-tenant-runtime \
  --runtime-origin https://new-runtime.example.com

Log in to deployment first and prepare DNS, HTTPS, and a proxy that serves the current Runtime at the new address. The command synchronizes registration and local configuration, recreates Runtime and Worker, and restarts the proxy. It supports server deployments without Cloudflare Tunnel. See Change the Tenant Domain.

Output for AI Operators and Scripts​

Deployment authorization and lifecycle commands accept --json. Check the tenant, directory, and current state before acting. Codes and passwords still require terminal interaction; JSON does not eliminate that interaction. On failure, record the error code and stop. Do not automatically re-register with --force, overwrite configuration, or format disks.

Runtime Commands​

Runtime commands are grouped under sl system, for example listing the MCP servers installed in a workspace app:

soln system workspace-app mcp-server list --app-code <app-code>

Every command accepts --json for machine-readable output, and System Commands lists the whole catalogue by category.

Local Config​

The CLI stores session data at:

~/.soln/config.json

The file permission is set to 0600.

Stored fields include:

  • baseUrl
  • callerType: "member"
  • email
  • token
  • sessionId
  • expiresAt
  • tenant

The CLI does not store passwords.

Exit Codes​

  • 0: success
  • 1: network or server error
  • 2: invalid arguments
  • 3: not logged in, expired session, or invalid session