> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Drive Orgo cloud computers from your terminal.

The Orgo CLI gives you complete control over your cloud computers from the
terminal: launch and manage workspaces and computers, open an interactive
shell, run multi-turn AI agent sessions, and pipe machine-readable output
into any other tool.

## Watch the CLI setup tutorial

Watch the walkthrough to install the CLI, sign in, create a computer, and hand
the CLI to a coding agent.

<iframe src="https://www.youtube.com/embed/g3IXtMHgZQo" title="Orgo CLI Setup - Control Cloud Computers from Your Terminal" style={{ width: '100%', aspectRatio: '16 / 9', border: 0, borderRadius: '12px' }} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerPolicy="strict-origin-when-cross-origin" loading="lazy" allowFullScreen />

[Watch Orgo CLI setup on YouTube](https://www.youtube.com/watch?v=g3IXtMHgZQo).

<Accordion title="Video transcript">
  This is a quick video on installing and setting up the Orgo CLI.

  If you haven't already, go to orgo.ai and create an account. You can see I have
  my account open here, and I'm in a workspace that has one computer.

  The first thing you want to do is go over to docs.orgo.ai and click into the CLI
  page. This page shows you the instructions and explains the specification for
  our CLI and everything it has available.

  For the CLI and everything else in our API documentation, you'll also see
  llms-full.txt on the bottom left. You can click into it and give it to Claude
  Code, Codex, or any coding agent for full context on how to install and use
  everything.

  Back on the CLI page, you can see all of these commands and the basic usage.
  I'll copy the one-line install command and run it. This usually takes a bit
  longer, but I already have it installed.

  I'm going to log out first to show you what it looks like to log back in. If
  you're already logged in to your Orgo account in the browser, this is simple.
  Type `orgo login` and it gives you a temporary code that expires in 10 minutes.
  Click Approve, then go back to the CLI. You can see it's authenticated now, and
  if you type `orgo`, it's there and ready to go.

  You can see a few of the common commands here, and I'll quickly show you some of
  the things you can run from the CLI. For every one of these commands, like
  workspaces, computers, templates, secrets, and SSH, you can type help to get the
  full set of what you can run with that command. Say `orgo computers help` and it
  gives you all of the options. There are a lot of options under the computers
  command, and you can control basically the entire computer lifecycle from the
  CLI.

  The first thing we want to do is target our workspace. The command to switch to
  a workspace is `orgo workspaces use`. We have my workspace here, and we can pass
  its name in quotes. Now we've switched over to my workspace, and if you run
  `orgo computers list`, you can see the one computer I have running in this
  workspace.

  From here I'll run a couple of quick commands. We can run
  `orgo computers create` and add `--help` to see the full set of inputs. We only
  need a few: `--name`, and we'll call this computer 123, then 8 GB of RAM and 2
  CPUs. That should be all we need to create a computer, so I'll run it. Within a
  few seconds it's created, and you can see the new computer popped up in this
  workspace. That's a simple example of setting up the CLI and creating a new
  computer.

  One last thing I'll show you. If you go back to `orgo`, one of the commands is
  `orgo manifest`. It prints a machine-readable list of every command in the CLI.

  Let's say you use Claude Code. I'll open Claude Code here and trust this folder.
  Then I'll say: "Hey, I want to use the Orgo CLI with the orgo commands. You can
  first run orgo manifest to understand the CLI format."

  You can paste a prompt like this into a Claude Code or Codex session to give it
  full context on how to use and interact with the CLI, through any coding agent
  such as Claude, Codex, or even Hermes. Once you paste it in, it tells you what
  computers you have and shows you everything it can do from here.

  That was a simple introduction to installing and setting up the Orgo CLI,
  logging in, creating a computer, and giving the context to a coding agent. I
  hope that was helpful.
</Accordion>

## Install

<CodeGroup>
  ```bash macOS / Linux theme={null}
  curl -fsSL https://orgo.ai/install.sh | bash
  ```

  ```bash npm theme={null}
  npm install -g orgo
  ```
</CodeGroup>

The npm package requires Node 20 or later. The install script needs no
system Node: it downloads its own into `~/.orgo/node`. No `sudo` needed.

## Sign in

```bash theme={null}
orgo login
```

Opens your browser, completes a device-code flow, and saves a credential
under `~/.orgo/credentials.json` (mode `0600`). To use a separate
identity in dev, set `ORGO_PROFILE=dev`.

## Commands

```text theme={null}
orgo                          Show account, workspace, and computer counts
orgo login / logout / whoami  Account management
orgo workspaces (ws)          list · create · use · current · rename · delete
orgo computers  (c)           list · create · start · stop · restart · resize · delete
                              bash · exec · clone · rename · wait · screenshot · view · vnc-password
orgo ssh <name>               Interactive shell on a computer
orgo templates                list · show · run · build · validate · publish · schema · delete
orgo files                    list · upload · download · export · delete
orgo secrets                  list · set · delete
orgo agent                    Multi-turn AI agent TUI (resumable sessions)
orgo run "<prompt>"           One-shot agent run
orgo resume [id] / sessions   Resume or list agent sessions
orgo api-keys                 Manage API keys
orgo billing                  balance · topup · history · portal
orgo completion <shell>       Print a bash, zsh, or fish completion script
orgo manifest                 Print every command and option as JSON
```

Every command accepts `--json` for machine-readable output and `--help`
for details. When stdout isn't a terminal, output switches to plain text
with no prompts. For JSON, pass `--json` or set `ORGO_JSON=1`.

## Give a coding agent the command list

`orgo manifest` prints every command and option as JSON, with aliases and
defaults. Tell Claude Code, Codex, or another coding agent to run it before it
uses the CLI, so it works from the real commands and flags instead of guessing.

```bash theme={null}
orgo manifest
```

## Create a computer

```bash theme={null}
orgo computers create
```

Interactive by default. It prompts for workspace, name, RAM, and CPU with
input validation. For scripts and CI, pass everything as flags:

```bash theme={null}
orgo computers create \
  --workspace my-workspace \
  --name agent-1 \
  --ram 4 \
  --cpu 1
```

| Flag | Values |
| - | - |
| `--ram <gb>` | 4, 8, 16, 32, 64 |
| `--cpu <cores>` | 0.5, 1, 2, 4, 8, 16 |
| `--disk <gb>` | Up to your plan's per-computer limit (grows only on resize) |
| `--os <os>` | linux (default), windows, macos, android |
| `--gpu <profile>` | 2q (2 GB) or 4q (4 GB), Linux-only. Falls back to CPU (with a warning) if no GPU host is free |
| `--region <codes>` | Region hint, comma-separated |
| `--resolution <WxHxD>` | Defaults to `1280x720x24` (`1920x1080x24` on macOS). Change it and your agent's coordinate space changes with it |
| `--snapshot <id>` | Boot from a snapshot or custom image |
| `--template <ref>` | Launch from a template, e.g. `claude-code` or `system/claude-code@1.0.0` |

Resize a running computer with `orgo computers resize <name> --ram 8 --cpu 4 --disk 64` (disk grows only; live RAM resize caps at 32 GB).

## SSH

```bash theme={null}
orgo ssh computer-name
```

Opens an interactive terminal session over WebSocket. Lands you in
`/root/Desktop` by default (override with `--cwd`). Standard SSH
disconnect sequences:

| Sequence | Action |
| - | - |
| `~.` (at start of line) | OpenSSH-style disconnect |
| `Ctrl+C` `Ctrl+C` (within 800ms) | Discoverable disconnect |
| `Ctrl+D` or `exit` | Standard shell exit |
| Single `Ctrl+C` | Forwarded to remote (interrupts process) |

## Agent TUI

```bash theme={null}
orgo agent
```

Multi-turn agent session with full conversation history, tool-call
visibility, and persistent sessions. Inside the TUI:

| Slash command | Action |
| - | - |
| `/help` | List slash commands |
| `/computer` | Switch the agent to a different computer (picker) |
| `/model` | Switch model: Sonnet 5 (default) or Opus 5 |
| `/sessions` | List saved sessions |
| `/resume` | Resume a prior session (picker) |
| `/compact` | Summarize older turns to shrink context |
| `/usage` | Token usage for this session |
| `/screenshot` | Save the live screenshot and open it |
| `/save <name>` | Set the session title |

Sessions auto-persist to `~/.orgo/sessions/` after every turn. Ctrl+C
loses nothing.

### Resume a session

```bash theme={null}
orgo resume            # interactive picker
orgo resume <id>       # direct
orgo sessions          # list saved sessions
```

## One-shot run

For scripts and CI:

```bash theme={null}
orgo run "open chrome and search for hermes" --computer agent-1
```

Streams text, tool calls, and tool results to stdout. Add `--json` to
get a single structured object at the end:

```json theme={null}
{
  "text": "Chrome is open on the Google homepage…",
  "tool_calls":   [{ "id": "toolu_…", "name": "computer", "input": { … } }],
  "tool_results": [{ "tool_use_id": "toolu_…", "display": "[screenshot]" }],
  "errors": [],
  "usage": { "prompt_tokens": 1420, "completion_tokens": 312, "total_tokens": 1732 },
  "computer": { "id": "…", "name": "agent-1" }
}
```

## Run commands on a computer

One-shot actions for scripts and CI:

```bash theme={null}
orgo computers bash agent-1 -c "ls -la"          # shell command (or pipe via stdin)
orgo computers exec agent-1 --code "print(2+2)"  # Python (--file or stdin also work)
orgo computers screenshot agent-1 -o shot.png    # save a PNG
orgo computers view agent-1                      # show the screen in your terminal
orgo computers clone agent-1                     # duplicate, preserving disk state
orgo computers rename agent-1 --to agent-2
orgo computers vnc-password agent-1              # print the VNC / terminal password
```

## Templates

Reproducible computer definitions: build once, launch anywhere. See the [Templates guide](/guides/templates/introduction) for the full schema.

```bash theme={null}
orgo templates list                    # your templates plus curated ones
orgo templates show claude-code        # inspect a template
orgo templates run claude-code         # launch a computer from a template
orgo templates build my-template       # build a published template into a snapshot (Scale plan; streams the log live)
orgo templates validate ./template.yaml
orgo templates publish ./template.yaml
orgo templates schema                  # print the template JSON Schema
```

Or launch straight from a template at create time: `orgo computers create --template claude-code`.

## Files and secrets

```bash theme={null}
# Files - upload caps at 10 MB; for larger data, pull it in from inside the computer
orgo files list
orgo files upload ./data.csv
orgo files download <id>
orgo files export --computer agent-1 --path /root/Desktop/report.csv
orgo files delete <id>

# Secrets - encrypted, write-only, and loaded by templates that declare them
orgo secrets list
orgo secrets set OPENAI_API_KEY
orgo secrets delete OPENAI_API_KEY
```

## API keys

```bash theme={null}
orgo api-keys list
orgo api-keys create --name ci --workspace my-workspace
orgo api-keys delete <id>
```

Keys can be scoped to a single workspace, which is useful for CI tokens that
should only see one workspace's resources.

## Environment

| Variable | Purpose |
| - | - |
| `ORGO_API_KEY` | Use this key directly (skips `~/.orgo/credentials.json`) |
| `ORGO_API_BASE_URL` | Point at a different API host |
| `ORGO_PROFILE` | Credential profile (default: `default`) |
| `ORGO_JSON=1` | Force JSON output everywhere |
| `ORGO_NO_COLOR=1` | Disable ANSI colors (also respects `NO_COLOR`) |

## Shell completion

The CLI ships with bash, zsh, and fish completion scripts. `orgo completion <shell>` prints the script. Source it from your shell config to enable it:

```bash theme={null}
# zsh
echo 'source <(orgo completion zsh)' >> ~/.zshrc

# bash
echo 'source <(orgo completion bash)' >> ~/.bashrc

# fish
orgo completion fish | source
```

Completion is dynamic. It queries your live workspaces and computers, so
`orgo ssh <Tab>` shows your actual computers.

## License

MIT.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.