Command-Line Interface (CLI)

The Scaleout Edge Command-Line Interface (CLI) is designed to streamline management of the Scaleout Edge platform, making it easier for users to deploy, monitor and interact with their Edge network.

With the Scaleout Edge CLI, users can:

  • Start and manage Scaleout Edge services such as the combiner, controller, API server, and Server Function hooks (requires Enterprise license or specific research related agreement).

  • Start and manage clients.

  • Interact with the controller to:

    • Manage sessions, including starting, stopping, and monitoring their progress.

    • Retrieve data and results related to sessions, such as aggregated models and validation metrics.

    • Query the state of the network, including the status of connected combiners and clients.

For detailed usage and examples, refer to the sections below.

Scaleout CLI (open source)

The scaleout commands allow users to log in to Scaleout Edge and interact with the platform.

Authentication and contexts

The standard way to use the CLI is to log in once with scaleout login. This creates a saved context that stores your instance URL and credentials. All subsequent commands automatically use the active context — no need to pass --host or --token every time.

# 1. Log in — opens a browser window for authentication
scaleout login https://edge.scaleoutsystems.com

# 2. All commands now work without extra flags
scaleout session list
scaleout model list

The --host (-H) and --token flags are only needed when you want to override the active context, for example to target a different instance in a script or CI environment.

Commands:

login

  • scaleout login - Log in to the Scaleout CLI by providing the URL to your Scaleout Edge instance. A browser window will open for authentication. Example:

scaleout login <url-to-instance>

context

The scaleout context commands allow users to list and switch between saved CLI contexts (i.e. authenticated instances).

  • scaleout context - List all saved contexts, or switch to a specific one by name or index. Example:

scaleout context
scaleout context production
scaleout context 2

remove

  • scaleout remove - Remove a saved CLI context by name or index. Example:

scaleout remove production
scaleout remove 2 --yes

run

The scaleout run commands allow users to run entry points and prepare the environment for Scaleout Edge projects.

  • scaleout run build - Run the build entry point for a Scaleout Edge project, defined in scaleout.yaml. Example:

scaleout run build --path /path/to/project/client

  • scaleout run install - Install the package environment from a scaleout.yaml into the active Python environment. Example:

scaleout run install --path /path/to/project/client

package

The scaleout package commands allow users to create and manage compute packages.

  • scaleout package create - Create a new package tarball for a Scaleout Edge project. Example:

scaleout package create --path /path/to/project/client

  • scaleout package set-active - Upload a package and set it as the active compute package. Example:

scaleout package set-active --file package.tgz --name my-package

  • scaleout package list - List all packages in your Scaleout Edge project. Example:

scaleout package list

  • scaleout package get - Retrieve a specific package by ID. Example:

scaleout package get --id <package-id>

model

The scaleout model commands allow users to manage models in your Scaleout Edge project.

  • scaleout model set-active - Upload a model file and set it as the active (seed) model. Example:

scaleout model set-active --file seed.npz

  • scaleout model list - List all models in your Scaleout Edge project. Example:

scaleout model list

  • scaleout model get - Retrieve a specific model by ID. Example:

scaleout model get --id <model-id>

client

The scaleout client commands allow users to configure, start and inspect Scaleout Edge clients.

  • scaleout client start - Start a Scaleout Edge client using a specified configuration. The --api-url and --token flags are required here because the client connects directly to an instance rather than using the CLI context. The token can be retrieved from the Scaleout Edge UI. Client behaviour can be further tuned via Client Environment Variables. Example:

scaleout client start --api-url https://edge.scaleoutsystems.com --token <token>

  • scaleout client get-config - Generate a client configuration YAML file with a unique client ID and token. Example:

scaleout client get-config --name my-client

  • scaleout client list - List all active Scaleout Edge clients in the network. Example:

scaleout client list

  • scaleout client get - Retrieve a specific client by ID. Example:

scaleout client get --id <client-id>

session

The scaleout session commands allow users to start, stop and list sessions in Scaleout Edge.

  • scaleout session start - Start a new federated learning session. Example:

scaleout session start --name my-session --rounds 10 --aggregator fedavg

  • scaleout session stop - Stop the currently running session. Example:

scaleout session stop

  • scaleout session list - List all sessions in your Scaleout Edge project. Example:

scaleout session list

  • scaleout session get - Retrieve a specific session by ID. Example:

scaleout session get --id <session-id>

round

The scaleout round commands allow users to retrieve and list round information.

  • scaleout round list - List all rounds in your Scaleout Edge project. Example:

scaleout round list

  • scaleout round get - Retrieve information for a specific round. Example:

scaleout round get --id <round-id>

combiner

The scaleout combiner commands allow users to list and inspect combiners in the Scaleout Edge network.

  • scaleout combiner list - List all combiners in your Scaleout Edge project. Example:

scaleout combiner list

  • scaleout combiner get - Retrieve a specific combiner by ID. Example:

scaleout combiner get --id <combiner-id>

  • scaleout combiner set-public-hostname - Set the public hostname for a combiner. Example:

scaleout combiner set-public-hostname --id <combiner-id> <hostname>

validation

The scaleout validation commands allow users to retrieve and list validation results.

  • scaleout validation start - Start a validation run for a given session and model. Example:

scaleout validation start --session-id <session-id> --model-id <model-id>

  • scaleout validation list - List all validation results for a project. Example:

scaleout validation list

  • scaleout validation get - Retrieve a specific validation result by ID. Example:

scaleout validation get --id <validation-id>

status

The scaleout status commands allow users to check the status of the Scaleout Edge network.

  • scaleout status list - List status entries for your Scaleout Edge project. Example:

scaleout status list

  • scaleout status get - Get a specific status entry by ID. Example:

scaleout status get --id <status-id>

Scaleout core (Enterprise)

The scaleoutcore commands allow users to start and manage Scaleout Edge core services, such as the combiner, controller, API server, and Server Function hooks (requires Enterprise license or specific research related agreement).

Commands:

combiner

The scaleoutcore combiner commands allow users to start and manage (scale) the Scaleout Edge combiner service.

  • scaleoutcore combiner start - Start the Scaleout Edge combiner service. Example:

scaleoutcore combiner start

controller

The scaleoutcore controller commands allow users to start and manage the Scaleout Edge controller service.

  • scaleoutcore controller start - Start the Scaleout Edge controller service. Example:

scaleoutcore controller start

api-server

The scaleoutcore api-server commands allow users to start (scale) and manage the Scaleout Edge API server service.

  • scaleoutcore api-server start - Start the Scaleout Edge API server service. Example:

scaleoutcore api-server start

hooks

The scaleoutcore hooks commands allow users to start and manage (scale) the Scaleout Edge Server Function hooks service.

  • scaleoutcore hooks start - Start the Scaleout Edge Server Function hooks service. Example:

scaleoutcore hooks start

migration

The scaleoutcore migration commands allow users to manage the PostgreSQL database schema via Alembic migrations.

  • scaleoutcore migration generate - Generate a new migration script based on model changes. Example:

scaleoutcore migration generate --message "add new column"

  • scaleoutcore migration upgrade - Apply pending migrations to bring the database up to date. Example:

scaleoutcore migration upgrade

  • scaleoutcore migration verify - Verify that the database schema matches the expected revision. Example:

scaleoutcore migration verify

  • scaleoutcore migration current - Print the current database schema revision. Example:

scaleoutcore migration current

  • scaleoutcore migration check - Check whether the database schema is up to date (exits non-zero if migrations are pending). Example:

scaleoutcore migration check

  • scaleoutcore migration stamp - Mark the database at a specific revision without running migrations. Example:

scaleoutcore migration stamp --revision head