Find the command you need.
A task-first reference for the Shell CLI. Start with the common commands below; flags and technical details follow. Commands run on the host computer.
On this page
Start a session
shell starts a process in a local terminal and shares it. Use -- to separate Shell options from the program’s arguments.
shell <command> [arguments...]Share a new process in the background.
shellStart your default shell. On Windows, PowerShell is preferred, then COMSPEC.
shell --foreground claudeKeep local foreground interaction while sharing.
shell --read-only claudeAllow browser viewing, not input.
shell --name "Review" -- codexGive the session a readable name.
Find, attach and stop
Local and account lists are different. Use a full ID or an unambiguous local prefix of at least six characters.
shell listLocal sessions and relay state.
shell list --jsonLocal JSON on stdout. Can contain e2ee_password; treat it as secret.
shell lsOpen sessions in your linked account.
shell ls --allInclude ended account sessions.
shell ls --jsonAccount metadata as JSON, without session passwords.
shell attach <ID>Attach locally. Ctrl-X, then D detaches; Ctrl-] is a legacy alternative.
shell kill -- <ID>Stop one session. The -- also handles IDs beginning with a dash.
shell kill --allStops every locally managed session. Do not use it to clean up a single test.
Passwords
The complete share link and password grant browser access. Do not print them into shared logs.
shell password <ID>Reveal the active browser password locally.
shell password rotate <ID>Change password, salt and cipher generation; disconnect viewers and revoke MCP grants without restarting the task.
Account and remote start
Account linking is optional. Remote start grants additional authority to run commands on this machine.
shell authLink your machine through browser approval.
shell auth --no-browserPrint the approval URL and follow the callback instructions.
shell auth --allow-remote-startEnable browser-started sessions deliberately.
shell auth --no-remote-startDisable that capability.
shell whoamiShow the linked account.
shell logoutUnlink and revoke the account token.
shell daemon statusCheck the background listener.
shell daemon startStart the listener when authorized.
shell daemon stopStop the listener; a later Shell command may start it again.
shell agentRun the listener in the foreground.
shell service installInstall background service availability.
shell service statusInspect the installed service.
shell service uninstallRemove the background service.
MCP grants
A bearer is not a browser password. The grant permits server-side decryption for the controller. Read the MCP workflow before granting input.
shell mcp grant <ID> "Controller" observe 900Create an expiring observation grant; bearer printed once.
shell mcp grant <ID> "Controller" control 900Add input permission when the host and operator allow it.
shell mcp list <ID>List grant metadata.
shell mcp revoke <ID> <grant-id>Revoke one grant.
shell mcp revoke-all <ID>Revoke this session’s MCP grants.
Automation preferences
Only the session owner can change these settings. Unspecified switches are preserved. Consent does not imply a new agent summary or a team MCP gateway is running.
shell permissions <ID>Read the three independent preferences.
shell permissions <ID> --daily-briefing=trueAllow supported daily content publication.
shell permissions <ID> --mcp-team-access=trueSet team MCP consent; the team gateway is not implemented in this release.
shell permissions <ID> --briefing-team-access=trueSet separate team-briefing consent; current excerpt delivery remains owner-only.
shell briefings statusRead your default for new sessions.
shell briefings on --allEnable the default and your existing own sessions.
shell briefings offDisable the default. Add --all to also update your existing own sessions.
Start flags
Put these before the wrapped command. Options that control access are chosen at session creation.
- --read-only
Reject browser and MCP input.
- --name <name>
One-line session label, up to 120 characters.
- --foreground
Mirror and control the process in the launching terminal.
- --persistent <state-file>
Reuse a saved identity, password and URL. Does not restore process memory.
- --files
Allow on-demand regular-file access under the working directory. Requires E2EE.
- --files-root <directory>
Use another explicitly chosen file root.
- --auto-close <value>
Set an earlier deadline; task exit still closes the share.
- --json
New-session JSON goes to stderr and includes e2ee_password for encrypted sessions.
- --server <URL>
Override the relay URL.
- --e2ee
Compatibility flag; encryption is already the default.
- --no-e2ee
Disable payload encryption explicitly. Conflicts with password overrides and persistence.
- --version
Print the CLI version.
- -h, --help
Show help.
Set an auto-close deadline
A deadline cannot keep a task alive after it exits. Missing or invalid values return exit status 2.
shell --auto-close 30m claudeClose after a relative duration.
- Relative values
ms, s, m, h, d, w, mo, y. Examples: 1h30m or 2d 3h.
- Date and time
today 18:30, tomorrow 09:00, local ISO-like dates, RFC3339, or the next occurrence of HH:MM.
Environment variables
Use these only on the host. Password values are secrets; do not include them in bug reports.
- SHELL
Default command on Unix when no command is supplied.
- SHELL_ONLINE_SERVER
Default relay URL; --server overrides it.
- SHELL_ONLINE_E2EE_PASSWORD
Choose a unique browser password instead of the generated one.
- SHELL_ONLINE_INSTALL_DIR
Installer-only absolute writable destination.
Output and exit status
A fast-exiting task reports its exit status without printing a dead link. New-session JSON is on stderr; list JSON is on stdout. Redirect each deliberately and keep credential-bearing output private.
- e2ee_password
Included in encrypted start/local-list JSON. Not an MCP bearer.
- 0
Successful start, or a fast task that exited successfully.
- 1
Operational failure.
- 2
Invalid flags or arguments.
Help and aliases
The executable has an offline reference. Aliases do not change permissions or behavior.
shell help referenceRead the full built-in reference.
shell help <topic>Ask about a command or topic, such as start, files, attach, password, e2ee or docker.
shell psAlias for shell list.
shell stop <ID>Alias for shell kill.