Help / Developers

Developers

#substratalctl

substratalctl uses the Linux app's code, so it signs in the same way, sends Substratal-Version: 1 on every request and gets the same errors. It's built with the app: cargo build -p substratalctl, or run it from the Flatpak with flatpak run --command=substratalctl com.substratalapps.Hub.

#Examples

substratalctl health                        # GET /health
substratalctl version                       # this client, the API version it sends, the base URL
substratalctl login --email you@example.com # prompts for the password, then a 2FA code if needed
substratalctl whoami --json
substratalctl users list --query dana
substratalctl route substratal://admin/users/usr_42
substratalctl help-url KEY-03

On a desktop the session goes into your keyring. On a server without one, pass --no-keyring; you then sign in on each run. Use --api local (or SUBSTRATAL_API=local) for the API's devserver on localhost:8080, or pass any base URL. On failure it exits with status 1 and prints the request ID, which you can quote to support.

#Reference

#substratalctl

Command-line client for the Substratal Apps Platform API

Usage: substratalctl [OPTIONS] <COMMAND>

#Subcommands:

• health — Check that the API is up (GET /health)
• version — Show this client's version, the API version it sends, and the base URL
• login — Sign in with email and password (and a TOTP code if two-factor is on)
• logout — Sign out and forget the saved session
• whoami — Show the signed-in user and their platform permissions
• users — Manage users
• screens — List the Hub's screens (IDs, routes, who can use them)
• route — Resolve a route or substratal:// link to its screen
• help-url — Print the help-center URL for a screen ID, e.g. USR-01

#Options:

• --api <API> — API environment: production, local (the devserver on :8080) or a base URL

  Default value: production

• --no-keyring — Don't use the Secret Service; you sign in again each run

• --json — Print JSON instead of a table

#substratalctl health

Check that the API is up (GET /health)

Usage: substratalctl health

#substratalctl version

Show this client's version, the API version it sends, and the base URL

Usage: substratalctl version

#substratalctl login

Sign in with email and password (and a TOTP code if two-factor is on)

Usage: substratalctl login [OPTIONS] --email <EMAIL>

#Options:

• --email <EMAIL>
• --password-env <VAR> — Read the password from this environment variable instead of prompting

#substratalctl logout

Sign out and forget the saved session

Usage: substratalctl logout

#substratalctl whoami

Show the signed-in user and their platform permissions

Usage: substratalctl whoami

#substratalctl users

Manage users

Usage: substratalctl users <COMMAND>

#Subcommands:

• list — List users (GET /users); needs users.list

#substratalctl users list

List users (GET /users); needs users.list

Usage: substratalctl users list [OPTIONS]

#Options:

• -q, --query <QUERY> — Search by name, email or usr_ ID prefix

• --limit <LIMIT>

  Default value: 50

#substratalctl screens

List the Hub's screens (IDs, routes, who can use them)

Usage: substratalctl screens [OPTIONS]

#Options:

• --all — Include web-only screens (the Console)

#substratalctl route

Resolve a route or substratal:// link to its screen

Usage: substratalctl route <PATH>

#Arguments:

• <PATH>

#substratalctl help-url

Print the help-center URL for a screen ID, e.g. USR-01

Usage: substratalctl help-url <SCREEN_ID>

#Arguments:

• <SCREEN_ID>

This document was generated automatically by clap-markdown.

Last updated 2026-10-23 · Built 2026-10-25 from a9ef3be · API 1.0.0-draft.13 · Substratal-Version: 1