# CLI

The orkestr CLI (`orkestr-cli`) puts every REST endpoint behind a Python entry point. Useful in CI / CD scripts, one-off ops, and on any machine where opening the console is friction. Same auth (API tokens) and same plan limits as the REST API.

## Installation

Install from PyPI. Requires Python 3.10+.

```bash
pip install orkestr-cli
```

Verify:

```bash
orkestr --version
# orkestr, version 0.4.0
```

## Authentication

Mint an API token in the console (Settings -> API tab) and paste it into `orkestr login`. The CLI stores the token in your user config so subsequent commands don't re-prompt.

`orkestr login`

Authenticate with an API token.

```
$ orkestr login
API token: ****
Logged in as deploy-bot.
```

`orkestr logout`

Clear stored credentials.

`orkestr whoami`

Show current user info.

```
$ orkestr whoami
  Username:  deploy-bot
  Email:     bot@example.com
  Plan:      pro
  Active:    True
```

`orkestr set-url <url>`

Set the API base URL. Defaults to `https://api.orkestr.eu`.

## Quick start

The fastest path from a git repo to a live URL is two commands: `orkestr init` to create and link the project, then `orkestr deploy .` to ship it.

> **Requirements**
>
> - An orkestr account, and an API token (console, Settings -> API tab) passed to `orkestr login`.
> - The repo's git provider (GitHub, GitLab, Bitbucket, or Codeberg) connected to that account, so orkestr can read and clone the repo. Connect it in the console, or check with `orkestr connections list`.
> - Your code pushed to that provider on the branch you deploy - orkestr builds from the remote repository, not your local working copy.
> - Run `orkestr init` from inside the repo (it reads `.git` for the repo URL and branch), or pass `--repo` and `--branch` explicitly.
> - Room in your plan for another project (Starter allows 1).

```bash
# From inside your app's git repo
$ orkestr login          # paste an API token (once)
$ orkestr init           # detect name, repo, branch -> create the project
$ orkestr deploy .       # build, wait, and print the live URL

  OK   clone
  OK   analyze
  OK   build
  OK   deploy
  OK   finalize

  Live at https://my-api.orkestr.run
```

`orkestr init` writes a gitignored `.orkestr/config.json` that links the directory to the project, so `orkestr deploy .` knows what to ship. Commit nothing - the file is local to your checkout.

`orkestr init`

Link the current directory to a new project. Detects the project name from the directory, the git repo and branch from .git, picks the service for monorepos, creates the project, and writes .orkestr/config.json. Press Enter to accept each default, or pass -y to accept them all. Options: --dir, --name, --repo, --branch.

```
$ orkestr init
Initializing orkestr project in ~/code/my-api
Logged in as deploy-bot.

Project name [my-api]:
Git repository [https://github.com/user/my-api]:
Branch [main]:
  Scanning the repo for services ...

  Name:     my-api
  Repo:     https://github.com/user/my-api
  Branch:   main
  Service:  (repo root)
  DNS:      my-api.orkestr.run

Create this project? [Y/n]:

Project 'my-api' created and linked.
  Domain:  my-api.orkestr.run
  Config:  .orkestr/config.json

Next: orkestr deploy .
```

## Projects

`orkestr projects list`

List all projects.

```
$ orkestr projects list
  Name          Framework   Status   Created
  my-api        fastapi     active   2026-03-30 18:37:31
  frontend-app  react       active   2026-03-28 10:15:22
```

`orkestr projects create <name> --repo <url>`

Create a new project from a git repository.

```
$ orkestr projects create my-api --repo https://github.com/user/repo
Project 'my-api' created.
  ID:      04cc3d67-ded5-4f05-92e4-8e52716e0ec6
```

`orkestr projects show <name>`

Show project details. Accepts name or UUID.

`orkestr projects update <name> [options]`

Update project settings (--display-name, --description, --branch).

`orkestr projects analyze <name>`

Detect framework, port, and resource requirements.

`orkestr projects env-vars <name>`

Show decrypted project-level env vars.

`orkestr projects webhook <name>`

Show webhook info: provider, URL, last delivery.

`orkestr projects webhook-toggle <name> [--enable / --disable]`

Enable or disable auto-deploy on git push.

`orkestr projects delete <name>`

Delete a project and destroy its infrastructure.

## Environments

`orkestr envs list <project>`

List environments for a project.

`orkestr envs create <project> <name> --branch <branch>`

Create a new environment.

`orkestr envs update <project> <env_id> [options]`

Update environment (--branch, --auto-deploy / --no-auto-deploy).

`orkestr envs env-vars <project> <env_id>`

Show decrypted env vars for an environment.

`orkestr envs delete <project> <env_id>`

Delete an environment.

## Deployments

`orkestr deploy [project]`

Build and deploy, streaming the pipeline steps and waiting until the app is live, then print its URL. Pass "." or omit the project to deploy the one linked to the current directory by orkestr init. Use --detach to fire the deploy and return immediately (for CI), --env to target an environment, and --timeout to cap the wait (default 600s).

```
$ orkestr deploy .
  OK   clone
  OK   analyze
  OK   build
  OK   deploy
  OK   finalize

  Live at https://my-api.orkestr.run
```

`orkestr deployments list <project>`

List deployment history.

`orkestr deployments show <id>`

Show deployment details and pipeline steps.

`orkestr deployments logs <id>`

Show full pipeline logs by step.

`orkestr deployments build-log <id>`

Full build output for a deployment.

`orkestr deployments rollback <id>`

Rollback to a previous deployment.

## Functions

`orkestr functions list`

List your serverless functions.

`orkestr functions create <name> --display-name "<text>" --runtime <runtime> --code-file <path>`

Create a function. Runtime: python312, node22, ...

```
$ orkestr functions create webhook --display-name "Webhook" \
      --runtime node22 --code-file handler.js
Function 'webhook' created.
  ID:   ...
  URL:  https://fn-webhook.orkestr.run
```

`orkestr functions show <name>`

Show function details (URL, runtime, status).

`orkestr functions update <name> [options]`

Update code, deps, auth, env vars, idle timeout.

`orkestr functions deploy <name>`

Build and deploy the function.

`orkestr functions logs <name>`

Recent runtime logs from the container.

`orkestr functions invoke <name> --method POST --path / --body '{...}'`

Invoke a deployed function and print the response.

`orkestr functions env-vars <name>`

Show decrypted function env vars.

`orkestr functions metrics <name> [--period 1h]`

Function request metrics.

`orkestr functions rotate-key <name>`

Rotate the function API key.

`orkestr functions delete <name>`

Delete a function and destroy its container.

## Add-ons and backups

`orkestr addons list <project>`

List add-ons for a project.

`orkestr addons add <project> --type <postgres|redis> --name <name>`

Provision a new add-on.

```
$ orkestr addons add my-api --type postgres --name mydb
Add-on 'mydb' (postgres) provisioned.
  Status:      running
  Env Var:     DATABASE_URL
  Connection:  postgresql://...
```

`orkestr addons show <project> <addon_id>`

Show a single add-on with connection URL.

`orkestr addons auto-backup <project> <addon_id>`

Toggle daily auto-backup on / off.

`orkestr addons backup-info <project> <addon_id>`

Backup retention, daily quota, next run.

`orkestr addons delete <project> <addon_id>`

Destroy an add-on and its data.

`orkestr addons backups <project> <addon_id>`

List backups for an add-on.

`orkestr addons backup <project> <addon_id>`

Trigger a manual backup.

`orkestr addons download <project> <addon_id> <backup_id>`

Get a download URL for a backup.

`orkestr addons delete-backup <project> <addon_id> <backup_id>`

Delete a backup.

## Monitoring

`orkestr logs <project>`

Show application runtime logs (--lines, --env).

```
$ orkestr logs my-api --lines 50
Container: my-api-production

2026-03-30 INFO: Application startup complete
2026-03-30 INFO: Uvicorn running on 0.0.0.0:8000
```

`orkestr stats <project>`

Show container CPU, memory, and network stats.

`orkestr health <project>`

Show container health, uptime, and restart count.

`orkestr metrics <project> [--period 1h]`

Request rate, error rate, p50 / p95 / p99 latency.

`orkestr app-health <project>`

Live app health badge from traffic + last deploy.

`orkestr deployment-stats <project>`

Deployment success rate, average duration.

`orkestr sleep <project>`

Manually put a container to sleep.

`orkestr wake <project>`

Wake a sleeping container.

## Domains

`orkestr domains list`

List your projects with their custom domain status.

`orkestr domains verify <project>`

Re-check that the project domain DNS points to orkestr.

## Registry

`orkestr registry list <project>`

List Docker images for a project.

`orkestr registry scan <project> <tag>`

Trigger a security scan on an image.

`orkestr registry delete <project> <tag>`

Delete an image tag. Live tag is protected.

## Activity, notifications, dashboard

`orkestr activity`

Recent activity (audit log).

`orkestr dashboard`

Dashboard summary: project count, plan usage, recent deploys.

`orkestr notifications list`

50 most recent notifications.

`orkestr notifications read <id>`

Mark a notification as read.

`orkestr notifications read-all`

Mark all notifications as read.

## API tokens

`orkestr tokens list`

List your API tokens.

`orkestr tokens create <name> [--expires-in-days N]`

Create a token; the plaintext is shown exactly once.

`orkestr tokens delete <token_id>`

Revoke a token.

## Project groups (workspaces)

`orkestr groups list`

List your project groups.

`orkestr groups show <id>`

Show a group with its assigned projects.

`orkestr groups create <slug> --name "<name>"`

Create a group.

`orkestr groups add <group_id> <project>`

Assign a project to a group.

`orkestr groups remove <group_id> <project>`

Remove a project from a group.

`orkestr groups delete <group_id>`

Delete a group (projects are not deleted).

## Git provider connections

`orkestr connections list`

List configured OAuth providers and connection status.

`orkestr connections repos <provider>`

List repositories accessible via the given provider.

`orkestr connections disconnect <provider>`

Disconnect a git provider (auto-deploy stops).

## Sandboxes

The same binary drives [sandboxes](https://orkestr.eu/sandboxes) - isolated, ephemeral Linux VMs for running untrusted or agent-generated code. Your `orkestr login` token drives them too (a default-scoped token, or one carrying `sandboxes:read` / `sandboxes:write`).

`orkestr sbx create [template]`

Create a sandbox - an isolated, ephemeral Linux VM (default template `python-3.12`). Flags: `--size`, `--network`, `--region`, `--timeout`, `--pause-on-timeout`, `--auto-resume`.

```
$ orkestr sbx create python-3.12 --network restricted
created sbx_01H...  (python-3.12, restricted, fsn1)
```

`orkestr sbx list`

List your sandboxes. Filter with --status.

`orkestr sbx info <id>`

Show one sandbox.

`orkestr sbx exec <id> <cmd...>`

Run a command, stream output, and exit with its exit code (composes in scripts).

```
$ orkestr sbx exec sbx_01H... "python -c 'print(2**10)'"
1024
```

`orkestr sbx shell <id>`

Line-buffered interactive exec loop.

`orkestr sbx metrics <id>`

Live CPU / memory / lifetime usage.

`orkestr sbx pause|resume|kill <id>`

Snapshot and stop the meter, resume from a snapshot, or terminate.

## Global flags

These flags can be used with any command.

- `--json` - output raw JSON instead of formatted tables (great for scripting)
- `--api-url <url>` - override the API base URL for this command
- `--token <token>` - use a specific API token for this command
- `--version` - show CLI version
- `--help` - show help for any command

```bash
# Get JSON output for scripting
orkestr projects list --json

# Deploy to a specific environment
orkestr deploy my-api --env staging
```

> **See also**
>
> Every command's `--help` output mirrors the underlying [REST API](https://orkestr.eu/docs/api-reference) request shape. If a command isn't listed here, try `orkestr <command> --help`.