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

# CLI

> Deploy and manage OrbitLab from your terminal and CI pipelines with the `orbitlab` command.

The OrbitLab CLI does everything the dashboard does for your projects: deploy from Git, manage environment variables, read logs, attach domains, edit DNS, query databases, manage files and your organization, and pay for services. It talks to the [REST API](/api) with an API token.

## Install

```bash theme={null}
npm install -g @orbitlab/cli
orbitlab --version
```

The CLI needs Node.js 18.17 or later and has no other dependencies. You can also run it without installing: `npx @orbitlab/cli <command>`.

## Log in

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

The CLI shows a short code and opens your browser. Check that the code matches, choose which organizations the CLI may access, and click **Authorize**. The CLI then saves an API token in `~/.config/orbitlab/config.json`, readable only by you. The token expires after 90 days; run `orbitlab login` again when it does.

* Already have a token? Pipe it in so it stays out of your shell history: `orbitlab login --with-token < token.txt`
* On a server without a browser: `orbitlab login --no-browser` and open the printed link on any device.
* `orbitlab whoami` shows the account, organization and token in use.
* `orbitlab logout` revokes the saved token and removes it from the machine.

<Note>
  In CI, don't run `orbitlab login`. Create a token in **Dashboard → Settings → API tokens** and expose it as the `ORBITLAB_TOKEN` environment variable.
</Note>

## Choose an organization

Commands act on one organization at a time. By default it's the first organization you joined.

```bash theme={null}
orbitlab orgs ls              # * marks the organization in use
orbitlab orgs switch acme     # id, slug or name
orbitlab services ls --org beta
```

The organization is chosen from, in order: `--org`, the `ORBITLAB_ORG` variable, the [linked project](#link-a-directory), then `orbitlab orgs switch`. A token restricted to one organization always uses that organization.

## Link a directory

Link your project directory to its service so you don't have to repeat the service name:

```bash theme={null}
cd my-app
orbitlab link my-app
orbitlab deploy --wait
orbitlab env ls
```

`orbitlab link` writes `.orbitlab/project.json` (service and organization ids, no secrets) and adds `.orbitlab` to `.gitignore`. It works from any subdirectory. Remove it with `orbitlab unlink`. Commands also accept a service id, name or domain as an argument or with `--service`.

## Deploy from Git

Order an app, connect its repository, then deploy:

```bash theme={null}
orbitlab plans ls --type application
orbitlab buy app --plan app-1 --label api
orbitlab services ls
orbitlab services setup api --repo https://github.com/acme/api \
  --build-cmd "npm run build" --start-cmd "npm start" --env NODE_ENV=production
```

Private GitHub repositories are detected automatically once the GitHub App is installed (`orbitlab git connect`).

```bash theme={null}
orbitlab deploy                     # production branch
orbitlab deploy --commit 3f2c1ab    # a specific commit
orbitlab deploy --wait              # stream the build log; exit code 1 if it fails
orbitlab deployments ls
orbitlab deployments logs <deploymentId>
orbitlab restart
orbitlab settings set --branch release --root-dir apps/api
```

## Environment variables

```bash theme={null}
orbitlab env ls                   # values hidden; add --reveal to show them
orbitlab env set API_URL=https://api.example.com SENTRY_DSN=https://…
orbitlab env rm OLD_KEY
orbitlab env pull .env.local      # download to a file
orbitlab env push .env.production # upload a file
```

Changes apply on the next deploy or after `orbitlab restart`.

## Logs and metrics

```bash theme={null}
orbitlab logs --since 1h
orbitlab logs --follow --stream stderr
orbitlab logs -q "timeout"
orbitlab logs --runtime             # live output of the running container
orbitlab requests --status 5xx --since 30m
orbitlab metrics
orbitlab metrics --history --from 24h
```

## Domains and DNS

```bash theme={null}
orbitlab domains check example.cd
orbitlab domains buy example.cd --quantity 2
orbitlab domains add www.example.com       # attach to the linked service
orbitlab domains verify www.example.com    # after creating the printed DNS records
orbitlab domains update example.cd --auto-renew --lock --privacy
orbitlab domains auth-code example.cd
```

To move a domain's DNS to OrbitLab, run `orbitlab domains import example.com`, set the nameservers it prints at your registrar, then run `orbitlab domains activate example.com`.

```bash theme={null}
orbitlab dns ls example.com
orbitlab dns add example.com www CNAME web.orbitlab.sh
orbitlab dns add example.com @ MX mail.example.com --priority 10
orbitlab dns add example.com @ TXT "v=spf1 include:_spf.example.com ~all"
orbitlab dns update example.com <recordId> --value 203.0.113.10
orbitlab dns rm example.com <recordId>
```

## Databases

```bash theme={null}
orbitlab db ls
orbitlab db inspect app-db              # credentials for owners and admins
orbitlab db tables app-db
orbitlab db rows app-db users --limit 20
orbitlab db query app-db "SELECT count(*) FROM users"
orbitlab db create shop --service my-site   # shared hosting
```

## Files and SFTP

Paths are relative to the site root (WordPress, PHP) or to the app's persistent storage in `/app/data`.

```bash theme={null}
orbitlab files ls wp-content/uploads
orbitlab files get wp-config.php
orbitlab files put ./logo.png wp-content/uploads
orbitlab files mkdir backups
orbitlab files sftp
```

## WordPress

```bash theme={null}
orbitlab wp actions
orbitlab wp run cache:flush --wait
orbitlab wp run plugin:install --param slug=wordfence --wait
orbitlab wp reset-admin --password "a-long-new-password"
```

## Shared hosting

```bash theme={null}
orbitlab buy hosting --plan starter --period yearly
orbitlab hostings ls
orbitlab hostings add-website <hostingId> --template wordpress --label blog
orbitlab orders provision <orderId> --template php-starter
```

## Billing

```bash theme={null}
orbitlab buy vps --plan vps-1
orbitlab buy app --plan app-1 --pay mobile-money --phone +243812345678 --autopay --wait
orbitlab promo validate WELCOME --plan app-1
orbitlab orders ls
orbitlab orders invoice <orderId>
orbitlab billing ls
orbitlab billing renew service api
orbitlab billing autopay --disable
```

Orders are paid with Mobile Money: a payment request is sent to `--phone`, and the provider is detected from the number, or pass `--network`. Free orders, such as one fully covered by `--promo`, need no phone number. Card payments are currently unavailable.

## Organization and access

```bash theme={null}
orbitlab members ls
orbitlab invitations create dev@example.com --role admin
orbitlab members role dev@example.com member
orbitlab members rm dev@example.com
orbitlab tokens ls
orbitlab tokens rm <tokenId>
```

## Scripting and CI

* `--json` prints machine-readable output on stdout. Progress messages go to stderr.
* Commands that delete or change something important ask for confirmation. Pass `--yes` (`-y`) in scripts.
* Exit codes: `0` success, `1` failure (API error, failed deployment, domain not verified), `2` invalid usage.
* `orbitlab api` calls any [API endpoint](/api) with your credentials: `orbitlab api /v1/services -F type=app`.

Deploy a commit after your tests pass with GitHub Actions:

```yaml .github/workflows/deploy.yml theme={null}
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @orbitlab/cli deploy ${{ vars.ORBITLAB_SERVICE }} --commit ${{ github.sha }} --wait
        env:
          ORBITLAB_TOKEN: ${{ secrets.ORBITLAB_TOKEN }}
```

## Global options and environment variables

| Option            | Variable              | Description                                             |
| ----------------- | --------------------- | ------------------------------------------------------- |
| `--token <token>` | `ORBITLAB_TOKEN`      | API token to use instead of the saved login             |
| `--org <org>`     | `ORBITLAB_ORG`        | Organization id or slug                                 |
| `--api-url <url>` | `ORBITLAB_API_URL`    | API base URL (default `https://orbitlab.dev`)           |
| `--json`          |                       | Print JSON                                              |
| `-y`, `--yes`     |                       | Skip confirmations                                      |
| `--debug`         |                       | Log HTTP requests to stderr                             |
|                   | `ORBITLAB_CONFIG_DIR` | Where the login is saved (default `~/.config/orbitlab`) |
|                   | `NO_COLOR`            | Disable colors                                          |

## Command reference

Run `orbitlab help` for the list and `orbitlab <command> --help` for all options of a command.

| Command                         | Description                                                    |
| ------------------------------- | -------------------------------------------------------------- |
| `orbitlab login`                | Log in and save an API token on this machine                   |
| `orbitlab logout`               | Revoke the saved token and forget it                           |
| `orbitlab whoami`               | Show the current user, organization and token                  |
| `orbitlab tokens ls`            | List your API tokens                                           |
| `orbitlab tokens rm`            | Revoke an API token                                            |
| `orbitlab orgs ls`              | List your organizations                                        |
| `orbitlab orgs switch`          | Select the organization used by default                        |
| `orbitlab orgs inspect`         | Show an organization                                           |
| `orbitlab orgs rename`          | Rename the active organization                                 |
| `orbitlab members ls`           | List members                                                   |
| `orbitlab members role`         | Change a member's role (owner only)                            |
| `orbitlab members rm`           | Remove a member, or leave the organization                     |
| `orbitlab invitations ls`       | List pending invitations                                       |
| `orbitlab invitations create`   | Invite someone                                                 |
| `orbitlab invitations rm`       | Revoke an invitation                                           |
| `orbitlab invitations accept`   | Accept an invitation                                           |
| `orbitlab services ls`          | List services (apps, WordPress sites, VPS)                     |
| `orbitlab services inspect`     | Show a service, its live URLs and latest deployment            |
| `orbitlab services setup`       | Connect a Git repository to a new app and deploy it            |
| `orbitlab services rm`          | Delete a service's project (the subscription is kept)          |
| `orbitlab services retry`       | Retry provisioning a WordPress site stuck in pending           |
| `orbitlab link`                 | Link the current directory to a service                        |
| `orbitlab unlink`               | Remove the directory link                                      |
| `orbitlab settings get`         | Show build and Git settings                                    |
| `orbitlab settings set`         | Update build and Git settings                                  |
| `orbitlab firewall get`         | Show IP allow/block lists                                      |
| `orbitlab firewall set`         | Replace IP allow/block lists                                   |
| `orbitlab deploy`               | Deploy the production branch or a commit                       |
| `orbitlab deployments ls`       | List deployments                                               |
| `orbitlab deployments inspect`  | Show a deployment                                              |
| `orbitlab deployments logs`     | Print a build log                                              |
| `orbitlab deployments rm`       | Delete a deployment                                            |
| `orbitlab restart`              | Restart the running container                                  |
| `orbitlab env ls`               | List environment variables                                     |
| `orbitlab env set`              | Add or update environment variables                            |
| `orbitlab env rm`               | Delete environment variables                                   |
| `orbitlab env pull`             | Download environment variables to a .env file                  |
| `orbitlab env push`             | Upload variables from a .env file                              |
| `orbitlab logs`                 | Show application logs                                          |
| `orbitlab requests`             | Show HTTP request logs                                         |
| `orbitlab metrics`              | Show CPU, memory, network and storage usage                    |
| `orbitlab domains ls`           | List domains                                                   |
| `orbitlab domains inspect`      | Show a domain                                                  |
| `orbitlab domains check`        | Check whether a domain can be registered                       |
| `orbitlab domains search`       | Suggest domains for a keyword                                  |
| `orbitlab domains buy`          | Register a domain                                              |
| `orbitlab domains add`          | Attach a custom domain to a service                            |
| `orbitlab domains verify`       | Check DNS and activate a custom domain                         |
| `orbitlab domains remove`       | Detach a custom domain                                         |
| `orbitlab domains update`       | Change auto-renew, transfer lock, WHOIS privacy or nameservers |
| `orbitlab domains auth-code`    | Show the transfer (EPP) code                                   |
| `orbitlab domains import`       | Move a domain's DNS hosting to OrbitLab                        |
| `orbitlab domains activate`     | Finish a DNS import                                            |
| `orbitlab dns ls`               | List DNS records                                               |
| `orbitlab dns add`              | Create a DNS record                                            |
| `orbitlab dns update`           | Update a DNS record                                            |
| `orbitlab dns rm`               | Delete a DNS record                                            |
| `orbitlab db ls`                | List databases                                                 |
| `orbitlab db inspect`           | Show a database and its credentials                            |
| `orbitlab db create`            | Add a database to shared hosting                               |
| `orbitlab db rm`                | Delete a database                                              |
| `orbitlab db tables`            | List tables                                                    |
| `orbitlab db rows`              | Browse rows of a table                                         |
| `orbitlab db query`             | Run a SQL query                                                |
| `orbitlab files ls`             | List files                                                     |
| `orbitlab files get`            | Download a file                                                |
| `orbitlab files put`            | Upload a file                                                  |
| `orbitlab files mkdir`          | Create a directory                                             |
| `orbitlab files sftp`           | Show SFTP connection details                                   |
| `orbitlab wp actions`           | List managed WordPress actions                                 |
| `orbitlab wp run`               | Run a managed action                                           |
| `orbitlab wp job`               | Show an action job                                             |
| `orbitlab wp reset-admin`       | Reset the WordPress admin account                              |
| `orbitlab hostings ls`          | List shared hosting subscriptions                              |
| `orbitlab hostings inspect`     | Show a shared hosting and its websites                         |
| `orbitlab hostings add-website` | Create a website on a shared hosting                           |
| `orbitlab plans ls`             | List plans and prices                                          |
| `orbitlab templates ls`         | List deployable templates                                      |
| `orbitlab buy`                  | Order an app, shared hosting, VPS or domain                    |
| `orbitlab orders ls`            | List orders                                                    |
| `orbitlab orders inspect`       | Show an order                                                  |
| `orbitlab orders retry`         | Retry a payment                                                |
| `orbitlab orders provision`     | Set up the hosting or VPS of a paid order                      |
| `orbitlab orders invoice`       | Download an invoice                                            |
| `orbitlab billing ls`           | List subscriptions and renewal dates                           |
| `orbitlab billing renew`        | Renew a service, hosting or domain                             |
| `orbitlab billing autopay`      | Show or disable automatic renewal                              |
| `orbitlab billing providers`    | List Mobile Money providers                                    |
| `orbitlab promo validate`       | Preview a promo code                                           |
| `orbitlab git ls`               | List GitHub App installations                                  |
| `orbitlab git repos`            | List repositories OrbitLab can deploy                          |
| `orbitlab git connect`          | Install the GitHub App                                         |
| `orbitlab git disconnect`       | Uninstall the GitHub App                                       |
| `orbitlab api`                  | Call any API endpoint                                          |