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.
shell- Start your default shell. On Windows, PowerShell is preferred, then COMSPEC.
shell --foreground claude- Keep local foreground interaction while sharing.
shell --read-only claude- Allow browser viewing, not input.
shell --name "Review" -- codex- Give 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 list- Local sessions and relay state.
shell list --json- Local JSON on stdout. Can contain e2ee_password; treat it as secret.
shell ls- Open sessions in your linked account.
shell ls --all- Include ended account sessions.
shell ls --json- Account 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 --all- Stops 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 auth- Link your machine through browser approval.
shell auth --no-browser- Print the approval URL and follow the callback instructions.
shell auth --allow-remote-start- Enable browser-started sessions deliberately.
shell auth --no-remote-start- Disable that capability.
shell whoami- Show the linked account.
shell logout- Unlink and revoke the account token.
shell daemon status- Check the background listener.
shell daemon start- Start the listener when authorized.
shell daemon stop- Stop the listener; a later Shell command may start it again.
shell agent- Run the listener in the foreground.
shell service install- Install background service availability.
shell service status- Inspect the installed service.
shell service uninstall- Remove 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 900- Create an expiring observation grant; bearer printed once.
shell mcp grant <ID> "Controller" control 900- Add 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=true- Allow supported daily content publication.
shell permissions <ID> --mcp-team-access=true- Set team MCP consent; the team gateway is not implemented in this release.
shell permissions <ID> --briefing-team-access=true- Set separate team-briefing consent; current excerpt delivery remains owner-only.
shell briefings status- Read your default for new sessions.
shell briefings on --all- Enable the default and your existing own sessions.
shell briefings off- Disable 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 claude- Close 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 reference- Read the full built-in reference.
shell help <topic>- Ask about a command or topic, such as start, files, attach, password, e2ee or docker.
shell ps- Alias for shell list.
shell stop <ID>- Alias for shell kill.