ork CLI reference

ork turns an existing project into an OrkStage template, pushes it, and deploys and operates instances from your terminal or from CI. It reads Terraform and OpenTofu, CloudFormation, SAM and CDK, Kubernetes and Helm, Docker Compose, Dockerfiles and package manifests. It also detects Pulumi, Serverless, Bicep and ARM projects. The CLI is written in Rust and licensed under AGPL-3.0.

InstallCopy Anchor Link

curl -fsSL https://orkstage.io/install.sh | sh     # installs to ~/.local/bin

irm https://orkstage.io/install.ps1 | iex          # installs to %LOCALAPPDATA%\Programs\ork

For shell completions, run ork completions bash|zsh|fish|powershell|elvish > <your completion dir>.

Quick startCopy Anchor Link

ork login --api-url https://orkstage.example.com   # prompts for an API key (ork_live_…)
cd my-project
ork init                                           # scans and writes .ork/
ork scan                                           # what was detected, with evidence
# fill [placements] in .ork/config.toml: a cloud target and region per slot
ork up --publish --wait                            # push, publish, create the instance, deploy
ork status && ork logs api

Create the key with the ork CLI (developer) preset: instances:read, instances:deploy, templates:read, templates:write, imports:write. Add instances:write for ork instances create and ork up. Templates are shared by all tenants, so ork template push works only with an organization key (role PlatformAdmin). See API keys.

From an empty directoryCopy Anchor Link

A run against a local platform (pnpm platform:up in orkstage-dev) with the seeded simulation targets. Output is shortened.

mkdir shop && cd shop
ork init --tenant acme --environment development --name shop -y
# Template: nothing deployable was detected, so .ork/template.yaml is a starter (one web service).
# Created /home/me/shop/.ork/ with config.toml, template.yaml, inventory.json and .gitignore.

ork init leaves one line per placement slot to fill in .ork/config.toml:

[placements]
primary = { target = "Simulated AWS (us-east-1)", region = "us-east-1" }

ork up --publish --yes --wait
# Pushed template shop@0.1.0 (draft).
# Published shop@0.1.0.
# Created instance shop-development from shop@0.1.0.
# [phase:verify] All health and connectivity checks passed.
# [phase:finalize] Instance is READY.
# Deployment 01a12dd9-82d0-... succeeded.

ork status
# Status: READY   Health: HEALTHY
# Template: shop@0.1.0   Tenant: Acme Corp

Change the template, then publish and roll it out:

ork template push && ork template publish
ork preview --template-version 0.1.1
# Plan: 0 to create, 0 to update, 1 to delete, 2 unchanged (risk high)
ork upgrade --yes --wait
# [phase:prune] Deleting cache (no longer in the template)
# [phase:prune] 1 resource(s) removed: cache.
# Deployment 01a12e13-742b-... succeeded.

Day to day: ork logs api, ork triggers run restart-api --wait and ork incidents list. When the instance is no longer needed:

ork destroy --instance shop-development --confirm shop-development --wait

Production destroys wait for approval in the console; the CLI prints the link.

CommandsCopy Anchor Link

The targets commands need a platform API key (role PlatformAdmin) with the targets:manage and instances:read scopes. Create one under Integrations > API keys without a tenant.

Global flags and environmentCopy Anchor Link

Precedence: flags first, then environment variables, then .ork/config.toml, then the user config.

Output and exit codesCopy Anchor Link

With -o json, stdout carries exactly one JSON document with deterministic ordering. Progress goes to stderr as NDJSON, and errors go to stderr as { "error": { code, message, status, correlationId, help, exitCode } }. API errors always include the platform's message and correlation id.

The .ork/ folderCopy Anchor Link

api_url = "https://orkstage.example.com"
tenant = "acme"

[template]
name = "shop"

[instance]
slug = "shop-staging"
environment = "staging"

# Placement slot → cloud target (name or id) and region, one line per slot of the template.
[placements]
primary = { target = "aws-staging", region = "us-east-1" }
data = { target = "azure-data", region = "westeurope" }

[scan]
include = []
exclude = ["examples/**"]

CredentialsCopy Anchor Link

The CLI stores one key per API URL in the OS keychain: macOS Keychain, Windows Credential Manager, or Secret Service on Linux. Where no keychain is available (containers, CI runners without a desktop session), it writes them to credentials.toml (mode 0600) in the user config directory:

Keys are never written to the project.

How the scan worksCopy Anchor Link

1. Walk (CLI only). A parallel walk that respects .gitignore skips node_modules, .terraform, target, vendor, dist, hidden directories and CDK asset.* copies. It also skips files over 1 MiB (configurable) and files that are not valid UTF-8.
2. Detect each source kind. Terraform is parsed as HCL. The scan evaluates var.*, local.* and simple expressions, expands local modules per call and reports remote modules as unmapped. References such as aws_db_instance.main.address in a task definition become connections. CloudFormation tags in short form (such as !Ref, !GetAtt and !Sub) are normalized.
3. Merge. When several sources show the same component, it becomes one resource that keeps every source. IaC evidence wins over Kubernetes, and Kubernetes wins over Compose, Dockerfiles and package hints.
4. Infer. The scan adds a network when services or data stores need one, and an ingress plus DNS for a public HTTP service on a cloud provider. It then chooses placement slots and tags the template with its size (starter, growth or scale) and with what it found (containers, postgres, object storage).
5. Render and validate the template. Problems become warnings, so the scan never fails on bad input.

In the generated template, each image is a catalog reference named after its service (catalog://api). The resource's sourceImage property keeps the image the scan detected.