lua auth

lua auth manages the credential every other command uses. It changes nothing on the agent; it changes which account, and which access, the CLI acts with. Verified against lua-cli 3.33.0.

Synopsis

lua auth configure [--api-key <key> | --email <email> [--otp <code>]]
lua auth key [--force]
lua auth logout [--all] [--force]
lua auth sessions [--json]
lua auth sessions revoke <sessionId>

Description

configure stores one of two credential kinds. Email sign-in creates a renewable user session: a six-digit code is sent to the address, and the resulting user session is saved under ~/.lua-cli/sessions/ and refreshed automatically. It follows your current access, so joining an organization or creating an agent in the admin dashboard needs no new sign-in. --api-key validates an existing API key against the platform and saves it to ~/.lua-cli/credentials with mode 0600. Saving one kind removes the other, so a machine holds either a user session or a key. Both files hold the secret in plain text; the owner-only permission is the protection. Commands resolve the credential in this order: LUA_API_KEY from the shell or ./.env, then the saved user session, then the credentials file. When LUA_API_KEY is set, configure warns that it masks the credential it saved. The platform classifies a credential when it is used:

Credential	Form	What it can do
User session	email and code	Everything your account can, including `lua init --agent-name` and `--from-agent-id`
Legacy key	`api_` followed by a hex string	Acts as your user; can create and duplicate agents
Scoped key	`api_<uuid>.<secret>`	Acts as a key principal with the roles it was granted; cannot create or duplicate agents, so those `lua init` modes exit 10

key prints the stored API key, or LUA_API_KEY when it is set, after a confirmation. With a user session it prints You are signed in with a renewable session. No API key is stored. and exits 0. logout removes the local user session and credentials file and ends this device’s user session on the platform; --all ends every user session of your account. A saved API key is removed only locally and stays valid until you revoke it in the admin dashboard. When the platform cannot confirm the sign-out the CLI warns Local session removed, but Lua could not confirm the sign-out on its side. sessions lists the devices and apps signed in as you, one user session each, with its id, app and version, sign-in method, and last-seen time. sessions revoke <sessionId> signs one of them out.

Arguments

Argument	Values	Description
subcommand	`configure`, `key`, `logout`, `sessions`	Required; `lua auth` alone prints help
`sessionId`	an id from `lua auth sessions`	Required by `sessions revoke`

Options

Option	Description	Default
`--api-key <key>`	`configure`: validate and save this key without prompting	prompt
`--email <email>`	`configure`: send a sign-in code to this address (step 1)	prompt
`--otp <code>`	`configure`: verify the six-digit code for `--email` and save the user session (step 2)	—
`--force`	`key`, `logout`: skip the confirmation prompt	prompt
`--all`	`logout`: sign out everywhere	this device
`--json`	`sessions`: print the list as JSON	text list

Examples

lua auth configure

lua auth configure --email [email protected]

Output

✅ OTP sent successfully!

📬 Check your email, then run:
   lua auth configure --email [email protected] --otp <code>

lua auth configure --email [email protected] --otp 123456

--ci does not stop the prompts of configure, key, or logout; pass --api-key or --email, and --force for key and logout. Save a key on a build machine without prompts:

lua auth configure --api-key "$LUA_CI_KEY" --ci

In CI you can skip configure and export LUA_API_KEY instead; it takes precedence over anything saved. Print the stored key for a secret manager, then sign this device out:

lua auth key --force
lua auth logout --force

Review the signed-in devices and sign one out:

lua auth sessions --json
lua auth sessions revoke <sessionId>

Exit codes

Code	When
`0`	Success; `key` with no stored key; a declined confirmation
`1`	Invalid email, a code that is not six digits, `Invalid OTP`, or a server that does not offer per-device sessions
`3`	`sessions revoke` with an unknown id
`9`	The key failed validation; no credential for `sessions`
`10`	`sessions revoke` when per-device sign-out is not enabled for the account
`11`	The authentication service or the network is unavailable

SDK

CLI

REST API

Synopsis

Description

Arguments

Options

Examples

Exit codes

See also

​Synopsis

​Description

​Arguments

​Options

​Examples

​Exit codes

​See also

Synopsis

Description

Arguments

Options

Examples

Exit codes

See also