lium workspaces and lium keys

Since lium 0.0.43 — behind the server's WORKSPACES_ENABLED flag

lium workspaces, lium keys, --workspace and LIUM_WORKSPACE ship in lium 0.0.43 (lium#183). The server side (lium-platform#208, #123 and, for invite, #124) is merged too; until a deployment turns WORKSPACES_ENABLED on, the CLI sees no workspace object on GET /users/me and the team commands answer with the server's 403 Workspaces are not enabled yet.

Work in a team workspace from the CLI: see the workspaces you belong to, make one the default, run a single command in another, and mint the API key a team needs.

lium workspaces [list] [--json]                                  # since lium 0.0.43
lium workspaces members [WORKSPACE] [--json]                     # since lium 0.0.43
lium workspaces use WORKSPACE                                    # since lium 0.0.43
lium workspaces login [--email EMAIL] [--password-stdin]         # since lium 0.0.43
lium workspaces create NAME [--use]                              # since lium 0.0.43
lium workspaces invite EMAIL [WORKSPACE] [--role owner|admin|member]   # since lium 0.0.43
lium workspaces remove USER_ID_OR_EMAIL [WORKSPACE] [--yes]      # since lium 0.0.43
lium workspaces transfer-billing USER_ID_OR_EMAIL [WORKSPACE]    # since lium 0.0.43
lium workspaces delete [WORKSPACE] [--yes]                       # since lium 0.0.43
lium keys list [--workspace NAME] [--json]                       # since lium 0.0.43
lium keys create NAME [--workspace NAME] [--save] [--json]       # since lium 0.0.43
lium --workspace NAME <command>        # or -w NAME, or LIUM_WORKSPACE=NAME — since lium 0.0.43

Both groups (lium#183) work only when the server has workspaces on — the CLI looks for the workspace object on GET /users/me (lium-platform#123); otherwise every subcommand, login included, fails — given no workspace name, with exit 3 and Workspaces are not enabled on this server; given a name, with whatever the server answers on GET /workspaces — and every other command behaves as before. WORKSPACE is a name (case-insensitive) or id; left out, it is the one chosen with use, else the one the key acts in.

A key belongs to one workspace

An API key acts in the workspace it was created in and never selects another one (the server refuses a workspace header that names any other workspace). Choosing a workspace on the CLI therefore means choosing a key:

• lium workspaces use research (lium#183) stores research as the active workspace in ~/.lium/config.ini ([workspaces] active, plus a [workspace.research] section with its id) together with the key the command ran with, when that key acts there — LIUM_API_KEY=<a key bound to research> lium workspaces use research saves that key (the environment, not an argument, so the key stays out of ps). When no key for that workspace is saved, the command says so and names the fix.
• lium keys create ci --workspace research --save (lium#183) mints a key bound to research and saves it under that name, so --workspace research works from then on.
• lium --workspace research ps (or LIUM_WORKSPACE=research; lium#183) runs one command with the key saved for that workspace. ps and ls print Workspace: Research (member) under their table, up and rm print it before they act (· personal for the personal one). When no key is saved for the name you asked, the command refuses before any request — No API key is saved for workspace 'research'; run lium keys create <name> --workspace research --save — because a key acts in exactly one workspace and another key would run the command in another team on another balance. Without --workspace, the key is LIUM_API_KEY, else the one saved for the use default, else [api] api_key; when that key acts in another workspace than the use default, ps and ls warn on the workspace line, and up and rm stop with exit 2. ps --format json carries workspace_id per pod when the server sends it (lium-platform#123).

Session-only actions

Creating, inviting, removing, transferring billing and deleting reshape a team, and the server allows them only to a signed-in person, not to a key — so does anything on /keys. lium workspaces login (lium#183) signs in once (POST /users/login; e-mail prompted or --email, password prompted or --password-stdin for scripts; an account created with GitHub or Google sign-in sets a password with Forgot password on lium.io first) and keeps the session token in ~/.lium/config.ini ([session] token; LIUM_SESSION_TOKEN overrides it) for those subcommands. Without one they stop with This needs a browser session, not an API key: run lium workspaces login (or set LIUM_SESSION_TOKEN). list and members work with either a key (the one workspace it acts in, marked *; lium-platform#123 on the server) or a session (every workspace of the account with your role, → marking the one chosen with use). invite calls POST /workspaces/{id}/invitations — lium-platform#124.

Options

Subcommand	Flag	Effect
members, invite, remove, transfer-billing, delete	[WORKSPACE] (positional)	Workspace name or id (default: the one chosen with use, else the key's own)
list, members, keys list, keys create	--json	Machine-readable output
keys list, keys create	--workspace, -w NAME	Workspace name or id (default: the current one)
login	--email, --password-stdin	Account e-mail; read the password from stdin instead of prompting
create	--use	Also make it the default workspace
invite	--role	owner, admin or member (default member; admins cannot grant owner)
remove, delete	--yes, -y	Skip the confirmation prompt
keys create	--save	Keep the key in ~/.lium/config.ini for --workspace <name>
lium (root)	--workspace, -w NAME	Run one command with the key saved for that workspace; LIUM_WORKSPACE does the same

Examples

lium workspaces                                    # the workspace this key acts in — since lium 0.0.43
lium workspaces login                              # sign in once for the team actions — since lium 0.0.43
lium workspaces create research --use              # a team, made the default — since lium 0.0.43
lium workspaces invite ada@example.com --role admin  # since lium 0.0.43
lium keys create ci --workspace research --save    # a key for that team, saved for --workspace — since lium 0.0.43
lium --workspace research up --gpu H100 -y --no-ssh  # since lium 0.0.43
lium workspaces members research --json  # since lium 0.0.43

See also

• Workspaces — roles, the billing owner, invitations
• Workspaces API — the endpoints behind these commands, team-key rules, key scopes
• lium config — where the saved keys live