Manage and troubleshoot the Labor0 CLI

Select the workspace

Use l0 workspace list to see workspaces available to the signed-in account, l0 workspace current to see the current selection, and l0 workspace use <workspace-id> to change it. Confirm the workspace name in the command output and the workspace selector in Labor0 before starting work. Workspace authorization permission still applies after a local selection is made.

For remote commands, l0 context verifies the selected profile's saved workspace and project. Save a change with l0 context set --workspace <workspace-id> [--project <project-id>], or remove only the saved context with l0 context clear. Use --profile <name> for an independent profile. Runner and login-service commands remain tied to default and reject other profiles.

Use l0 auth status to verify the effective profile credential without displaying it. L0_API_KEY takes precedence when present; if logout reports that it remains effective, remove it through the shell, CI, or secret manager that supplied it rather than expecting the CLI to change the environment.

l0 auth logout removes only the selected locally stored credential and keeps non-secret context. To revoke the exact remote key too, use l0 auth logout --revoke; complete the fresh device-authorization page and wait for confirmed revocation before retrying. If login reports an unconfirmed key creation, do not retry automatically: inspect API keys in workspace settings first. If secure storage is unavailable, use L0_API_KEY for that invocation; the CLI does not create a plaintext fallback.

List profiles with l0 profile list. Before deleting a non-default profile, log it out, then run l0 profile delete <name> and confirm the displayed target. Profile deletion does not revoke a retained remote key; manage that key in workspace settings if you did not use logout --revoke.

Runner and service lifecycle

After setup, every scope-bearing runner command requires exactly one of --tenant, --workspace, or --project. The examples below use a Workspace; substitute one exact selector for a Tenant or Project runner. Commands never combine selectors or move an existing runner to another scope.

Need	Command	Visible evidence
Start	`l0 runner start --workspace <workspace-id>`	Status reports running.
Stop	`l0 runner stop --workspace <workspace-id>`	Status reports stopped; registration remains.
Retry	`l0 runner start --retry --workspace <workspace-id>`	A new status check reports the result.
Reconnect	`l0 runner reconnect --workspace <workspace-id>`	Fresh authorization completes and the same setup type is active.
Disconnect	`l0 runner disconnect --workspace <workspace-id>`	The CLI registration is disabled; local cache is retained.
Service status	`l0 service status`	The current-user service state is shown.
Service restart	`l0 service restart`	The service returns to its configured running state.
Remove login service	`l0 service uninstall`	The service definition is removed; runner registration and cache remain.

Stop before replacing a bundle or retrying a failed update. Reconnect only a CLI-managed registration. Do not use CLI reconnect on a manually registered runner.

Legacy CLI runner state is deliberately not started automatically. Recover an old Workspace registration explicitly with l0 runner migrate --workspace <workspace-id> --yes. Before authorization, the command reports the number of legacy cache bytes that will be permanently deleted; omit --yes in a terminal to use the confirmation prompt. Migration refuses an active legacy daemon or pending finalization, performs fresh authorization, reuses consent only for that same Workspace (otherwise pass --accept-local-execution-consent=v1), creates a replacement exact-scope runner, and removes the legacy managed configuration, desired-running state, and cache. Review disabled legacy rows in Workspace Settings before removing them.

Inspect and clear cache

Run l0 runner cache inspect --workspace <workspace-id> before clearing anything. It reports clearable bytes and skips every active scope. Then use l0 runner cache clear --workspace <workspace-id> and confirm the prompt, or add --yes only in an unattended workflow whose exact scope is already fixed. Cache clearing does not delete Labor0 task history and never clears active work.

Safe logs and diagnostic ZIPs

Use l0 runner diagnostics --workspace <workspace-id> --output <absolute-new-zip> to create one redacted local archive. Review it before sharing. It is not uploaded automatically and must not contain credentials, authorization values, prompts, transcripts, repository paths, provider output, or environment values. Never attach raw logs or a diagnostic ZIP containing private data to a public issue.

Use l0 diagnostics --output <absolute-new-zip> for the equivalent redacted remote-command checks. The destination must be an absolute path to a new file inside an existing directory that only your operating-system account can access, and the command does not print the private path. On macOS or Linux, create a private directory with mkdir -m 700 "$HOME/labor0-support", then run l0 diagnostics --output "$HOME/labor0-support/diagnostics.zip". If the command reports storagePermission, create a new private directory or correct the destination directory's ownership and permissions before retrying. l0 doctor can check secure storage, profile authentication, context, and remote reachability without changing state or signing in to a coding provider.

Recovery order

Confirm the selected workspace and run l0 doctor.
Check the runner with l0 runner status --workspace <workspace-id>.
If it is stopped, retry once with l0 runner start --retry --workspace <workspace-id>.
If authorization is stale, use l0 runner reconnect --workspace <workspace-id>; if the registration is no longer wanted, use l0 runner disconnect --workspace <workspace-id>.
If a login service is installed, use l0 service status and then l0 service restart.

For GitHub, payment, or passkey handoffs, keep the initiating command open. A successful browser action is complete only when the CLI observes the authoritative result. Closing or canceling the browser does not end the command; permission loss, interruption, and the ten-minute expiry do. Inspect the matching list or status command before retrying an uncertain operation. OAuth codes, Checkout state, and WebAuthn material must never be copied into the terminal or a support report.

In the browser, Auto prefers an eligible active local runner but may use hosted fallback. An active online CLI-managed runner does not currently enable Local only because Labor0 cannot confirm readiness for the selected coding-agent runtime. Local only never falls back to hosted execution. If hosted fallback is unacceptable, do not submit the browser task with Auto, because hosted work may begin before final attribution is available; stop before retrying until the final attribution is confirmed as Local runner.

Updates and support handoff

Follow Install the CLI to replace the complete bundle, including both executables, skills, and notices. After the update, verify both version commands and runner status. For support, provide the CLI version, operating system and architecture, the safe status result, and a reviewed redacted diagnostic ZIP only through the private support channel and only when requested. Never attach a diagnostics ZIP or raw logs to a public issue. Remove workspace names, paths, task text, credentials, tokens, and private URLs before sharing.

The visible completion evidence is a healthy status result for the intended workspace and a task or session detail showing final Local runner attribution.

What ready looks like

Recovery is complete when the selected workspace is explicit, the runner status is healthy, and support evidence has been reviewed for private values.