CreateOS CLI

 ██████╗██████╗ ███████╗ █████╗ ████████╗███████╗ ██████╗ ███████╗
██╔════╝██╔══██╗██╔════╝██╔══██╗╚══██╔══╝██╔════╝██╔═══██╗██╔════╝
██║     ██████╔╝█████╗  ███████║   ██║   █████╗  ██║   ██║███████╗
██║     ██╔══██╗██╔══╝  ██╔══██║   ██║   ██╔══╝  ██║   ██║╚════██║
╚██████╗██║  ██║███████╗██║  ██║   ██║   ███████╗╚██████╔╝███████║
 ╚═════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝   ╚═╝   ╚══════╝ ╚═════╝ ╚══════╝
  Your intelligent infrastructure CLI

The official command-line interface for CreateOS — manage your projects from the terminal.

Installation

macOS & Linux — install script (recommended)

curl -sfL https://raw.githubusercontent.com/NodeOps-app/createos-cli/main/install.sh | sh -

macOS & Linux — Homebrew

brew tap nodeops-app/tap
brew install createos

Nightly

Built daily from the latest commit on main. May contain unreleased features.

# Install script
curl -sfL https://raw.githubusercontent.com/NodeOps-app/createos-cli/main/install.sh | CREATEOS_CHANNEL=nightly sh -

# Homebrew
brew install createos --HEAD

Pin a specific version

curl -sfL https://raw.githubusercontent.com/NodeOps-app/createos-cli/main/install.sh | CREATEOS_VERSION=v0.0.3 sh -

Upgrade

createos upgrade

Or via Homebrew:

brew upgrade createos

Build from source

Requires Go 1.26+.

git clone https://github.com/NodeOps-app/createos-cli
cd createos-cli
go build -o createos .

Contributing

Pre-commit hooks

The repo ships with pre-commit hooks for secret detection and build verification. Set them up once after cloning:

pip install pre-commit detect-secrets
pre-commit install
detect-secrets scan > .secrets.baseline

Hooks that run on every commit:

Hook	Check
`detect-secrets`	Scans for accidentally committed secrets
`go-vet`	Runs `go vet ./...`
`go-build-tmp`	Verifies the project builds cleanly

If detect-secrets flags a false positive, audit and update the baseline:

detect-secrets audit .secrets.baseline

Getting started

1. Sign in

Choose one of the following methods:

Option A — Browser login (OAuth, recommended)

createos login

This opens your browser to complete sign in. Your session is saved automatically.

Option B — API token

Get your API token from your CreateOS dashboard, then run:

createos login --token <your-api-token>

Or run createos login interactively and select "Sign in with API token" when prompted.

In CI or non-interactive environments, you must use the --token flag.

2. Confirm your account

createos whoami

3. Link your project

createos init

4. Explore commands

createos --help

Commands

Authentication

Command	Description
`createos login`	Sign in with browser or API token
`createos logout`	Sign out
`createos whoami`	Show the currently authenticated user

Projects

Command	Description
`createos projects add`	Create a new project
`createos projects list`	List all projects
`createos projects get`	Get project details
`createos projects delete`	Delete a project
`createos projects suspend`	Pause a running project
`createos projects unsuspend`	Resume a suspended project

projects add flags:

Flag	Description
`--name`	Display name for the project
`--unique-name`	Unique name (lowercase, 4-32 chars)
`--type`	Project type: `vcs`, `image`, or `upload`
`--description`	Project description
`--framework`	Framework (e.g. `nextjs`, `reactjs-spa`, `vite-spa`)
`--runtime`	Runtime (e.g. `node:20`, `golang:1.25`, `dockerfile`)
`--port`	Port the application listens on
`--install-command`	Install command (e.g. `npm install`)
`--build-command`	Build command (e.g. `npm run build`)
`--run-command`	Run command (e.g. `npm run start`)
`--build-dir`	Build output directory
`--build-flag`	Build flags
`--run-flag`	Run flags
`--directory-path`	Root directory path (default: `.`)
`--github-owner`	GitHub account/org name (VCS projects, non-interactive)
`--repo`	GitHub repository full name, e.g. `owner/repo` (VCS, non-interactive)

Deploy

Command	Description
`createos deploy`	Deploy your project (auto-detects type)

Deploy flags:

Flag	Description
`--project`	Project ID (auto-detected from `.createos.json`)
`--branch`	Branch to deploy from (VCS/GitHub projects only)
`--image`	Docker image to deploy (image projects only, e.g. `nginx:latest`)
`--dir`	Directory to zip and upload (upload projects only, default: `.`)

Deploy behaviour by project type:

Project type	What happens
VCS / GitHub	Triggers from the latest commit. Prompts for branch interactively if not provided.
Upload	Zips the local directory (respects `.gitignore`), uploads, and streams build logs.
Image	Deploys the specified Docker image.

Files excluded from upload zip:

Sensitive and noisy files are always excluded: .env, .env.*, secrets/keys (*.pem, *.key, *.p12, etc.), node_modules, build artifacts (target, coverage, etc.), OS/editor files, and anything listed in your project's .gitignore.

Deployments

Command	Description
`createos deployments list`	List deployments for a project
`createos deployments logs`	Stream runtime logs for a deployment
`createos deployments build-logs`	Stream build logs for a deployment
`createos deployments promote`	Promote a deployment to an environment
`createos deployments retrigger`	Retrigger a deployment
`createos deployments sleep`	Put a running deployment to sleep
`createos deployments wakeup`	Wake up a sleeping deployment
`createos deployments cancel-build`	Cancel a deployment that is building

Environments

Command	Description
`createos environments list`	List environments for a project
`createos environments create`	Create a new environment
`createos environments delete`	Delete an environment

Environment Variables

Command	Description
`createos env list`	List environment variables for a project
`createos env set`	Set one or more environment variables
`createos env rm`	Remove an environment variable
`createos env pull`	Download environment variables to a local `.env` file
`createos env push`	Upload environment variables from a local `.env` file

Domains

Command	Description
`createos domains list`	List custom domains for a project
`createos domains create`	Create a custom domain for a project
`createos domains verify`	Check DNS propagation and wait for verification
`createos domains delete`	Delete a custom domain

Cron Jobs

Command	Description
`createos cronjobs list`	List cron jobs for a project
`createos cronjobs create`	Create a new HTTP cron job
`createos cronjobs get`	Show details for a cron job (including path, method, headers, body)
`createos cronjobs update`	Update a cron job's name, schedule, or HTTP settings
`createos cronjobs suspend`	Pause a cron job
`createos cronjobs unsuspend`	Resume a suspended cron job
`createos cronjobs activities`	Show recent execution history
`createos cronjobs delete`	Delete a cron job

HTTP settings flags (for create and update):

Flag	Description
`--path`	HTTP path to call, must start with `/`
`--method`	HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`
`--header`	Header in `Key=Value` format, repeatable
`--body`	JSON body to send with the request (only for POST, PUT, PATCH)

Templates

Command	Description
`createos templates list`	Browse available project templates
`createos templates info`	Show details about a template
`createos templates use`	Download and scaffold a project from a template

VMs

Command	Description
`createos vms list`	List VM instances
`createos vms get`	Get details of a VM
`createos vms deploy`	Deploy a new VM
`createos vms ssh`	Connect to a VM via SSH
`createos vms reboot`	Reboot a VM
`createos vms resize`	Resize a VM to a different plan
`createos vms terminate`	Permanently destroy a VM

Sandboxes

Sandboxes are fast-booting VMs — isolated environments you can exec into, sync files to, tunnel ports through, and snapshot at will.

Anywhere a command takes a sandbox, you can pass its full ID, its name, or just the first few characters of either — the same shortcut Docker allows:

createos sandbox rm sb-01243e     # enough of the ID to be unique
createos sandbox get my-box       # the name you gave it
createos sandbox exec my-b -- ls  # enough of the name to be unique

If what you type matches more than one sandbox, the CLI lists the matches and asks for a few more characters rather than guessing.

Command	Description
`createos sandbox create`	Create a new sandbox
`createos sandbox list`	List your sandboxes
`createos sandbox get`	Show details for one sandbox
`createos sandbox edit`	Change a sandbox's settings (public URL, SSH keys, auto-pause)
`createos sandbox pause`	Snapshot a running sandbox so you can resume it later
`createos sandbox resume`	Bring a paused sandbox back to life
`createos sandbox fork`	Clone a paused sandbox into a brand-new one
`createos sandbox rm`	Delete one or more sandboxes
`createos sandbox exec`	Run a command inside a sandbox
`createos sandbox shell`	Open an interactive shell inside a sandbox
`createos sandbox process`	Manage reconnectable processes and shell sessions
`createos sandbox sync`	Two-way file sync between your laptop and a sandbox
`createos sandbox push`	Copy a local file into a sandbox
`createos sandbox pull`	Copy a file out of a sandbox
`createos sandbox tunnel`	Forward a local port to a port inside a sandbox
`createos sandbox shapes`	List available sandbox sizes (vCPU / RAM / disk)
`createos sandbox rootfs`	List built-in OS images you can boot a sandbox from

sandbox create flags:

Flag	Description
`--shape`	Size of the sandbox (see `createos sandbox shapes`)
`--name`	Friendly name for the sandbox
`--rootfs`	Base image or custom template to start from
`--disk-mib`	Disk size in MiB (defaults to the shape's standard disk)
`--ssh-key`	Path to an SSH public key file (repeatable)
`--env`	Environment variable for every exec (repeatable): `KEY=VALUE`
`--egress`	Allowed outbound host/IP (repeatable). Empty = unrestricted.
`--network`	Private network to join at creation (repeatable): `<name\|id>`
`--disk`	S3 disk to mount at creation (repeatable): `<name\|id>:/mount/path`
`--ingress`	Give the sandbox a public HTTPS URL
`--auto-pause`	Auto-pause after inactivity (e.g. `10m`, `1h`). Omit to keep running.

When to use exec, shell, process, and PTY:

Use sandbox exec for quick non-interactive one-shot commands. Use sandbox shell when you want an immediate interactive terminal and do not need to reconnect later. Use sandbox process when the command should be manageable after it starts — list it, reconnect to output, send input, wait for it, signal it, or stop it. Add --pty/--tty/-t to process run or process start when the managed command needs terminal behavior.

Command	Description
`createos sandbox process run <sb> -- <cmd>`	Run a managed command, stream output, and return its exit code
`createos sandbox process start <sb> -- <cmd>`	Start a managed command and print its process ID
`createos sandbox process shell <sb>`	Start a persistent shell session that can be reattached
`createos sandbox process attach <sb> <proc>`	Reconnect to process output or a shell session
`createos sandbox process attach <sb>`	Pick a running process or shell session and attach to it
`createos sandbox process list <sb>`	List managed processes and shell sessions
`createos sandbox process get <sb> <proc>`	Show details for one managed process
`createos sandbox process input <sb> <proc>`	Write input to a process or shell session
`createos sandbox process close-stdin <sb> <proc>`	Close stdin for a pipe process
`createos sandbox process resize <sb> <proc>`	Resize a managed shell session
`createos sandbox process signal <sb> <proc> <signal>`	Send a signal such as `SIGINT` or `SIGTERM`
`createos sandbox process wait <sb> <proc>`	Wait for a managed process to exit
`createos sandbox process stop <sb> <proc>`	Stop a process and anything it started

Interactive attach without a process ID shows running managed processes. Pick a PTY shell for an interactive terminal, or pick a pipe process to follow its stdout/stderr output. Managed shell shortcuts are fixed: Ctrl-] detaches, Ctrl-N creates a new shell and switches to it, and Ctrl-P opens the process picker.

Sandbox sub-resource commands:

Command	Description
`createos sandbox disk create`	Register an S3 bucket as a mountable disk
`createos sandbox disk ls`	List your disks
`createos sandbox disk show <name\|id>`	Show details for one disk
`createos sandbox disk attach <sb> <disk> <path>`	Mount a disk into a running sandbox
`createos sandbox disk detach <sb> <disk> <path>`	Unmount a disk from a sandbox
`createos sandbox disk rm <name\|id>`	Delete a disk (auto-detaches first)
`createos sandbox network create <name>`	Create a private network
`createos sandbox network ls`	List your networks
`createos sandbox network show <name\|id>`	Show a network and its attached sandboxes
`createos sandbox network attach <net> <sb>`	Add a sandbox to a network
`createos sandbox network detach <net> <sb>`	Remove a sandbox from a network
`createos sandbox network rm <name\|id>`	Delete a network (auto-detaches first)
`createos sandbox firewall show <sandbox>`	Show what the sandbox is allowed to reach
`createos sandbox firewall set <sb> <host…>`	Replace the outbound allowlist
`createos sandbox firewall clear <sandbox>`	Open the firewall — allow all outbound traffic
`createos sandbox template submit <name>`	Build a Dockerfile into a sandbox image
`createos sandbox template ls`	List your custom sandbox images
`createos sandbox template show <name\|id>`	Show details for one image
`createos sandbox template logs <name\|id>`	Show (or follow) the build output for an image
`createos sandbox template rm <name\|id>`	Delete a custom image

Webhooks

Command	Description
`createos webhooks list`	List all webhook endpoints
`createos webhooks get`	Show details for a webhook endpoint
`createos webhooks create`	Create a new webhook endpoint
`createos webhooks delete`	Delete a webhook endpoint
`createos webhooks suspend`	Suspend a webhook endpoint
`createos webhooks resume`	Resume a suspended webhook endpoint

Quick Actions

Command	Description
`createos init`	Link the current directory to a CreateOS project
`createos status`	Show a project's health and deployment status
`createos open`	Open a project's live URL in your browser
`createos scale`	Adjust replicas and resources for an environment

OAuth Clients

Command	Description
`createos oauth-clients list`	List your OAuth clients
`createos oauth-clients create`	Create a new OAuth client
`createos oauth-clients instructions`	Show setup instructions for a client
`createos oauth-clients delete`	Delete an OAuth client

Me

Command	Description
`createos me oauth-consents list`	List OAuth consents
`createos me oauth-consents revoke`	Revoke an OAuth consent

Other

Command	Description
`createos ask`	Ask the AI assistant to help manage your infrastructure
`createos upgrade`	Upgrade createos to the latest version
`createos version`	Print the current version

Non-interactive / CI usage

All commands accept flags so they work in CI and non-interactive environments. Destructive commands require --force to skip the confirmation prompt.

# Deploy
createos deploy                                      # upload project — zips current dir
createos deploy --dir ./dist                         # upload project — zip a specific dir
createos deploy --branch main                        # VCS project — deploy from main
createos deploy --image nginx:latest                 # image project

# Create projects
createos projects add --name "My API" --unique-name my-api \
  --type image --port 8080

createos projects add --name "My App" --unique-name my-app \
  --type upload --framework nextjs --runtime node:20

createos projects add --name "My App" --unique-name my-app \
  --type vcs --framework nextjs --runtime node:20 \
  --github-owner myorg --repo myorg/my-app

# Projects
createos projects get --project <id>
createos projects delete --project <id> --force
createos projects suspend --project <id> --force
createos projects unsuspend --project <id> --force

# Deployments
createos deployments list --project <id>
createos deployments logs --project <id> --deployment <id>
createos deployments build-logs --project <id> --deployment <id>
createos deployments promote --project <id> --deployment <id> --environment <id>
createos deployments retrigger --project <id> --deployment <id>
createos deployments sleep --project <id> --deployment <id> --force
createos deployments wakeup --project <id> --deployment <id>
createos deployments cancel-build --project <id> --deployment <id> --force

# Environments
createos environments list --project <id>
createos environments create --project <id> --name "Staging" --unique-name staging --branch develop
createos environments delete --project <id> --environment <id> --force

# Environment variables
createos env list --project <id> --environment <id>
createos env set KEY=value --project <id> --environment <id>
createos env rm KEY --project <id> --environment <id>
createos env pull --project <id> --environment <id> --force
createos env push --project <id> --environment <id> --force

# Domains
createos domains list --project <id>
createos domains create --project <id> --name example.com
createos domains verify --project <id> --domain <id> --no-wait
createos domains delete --project <id> --domain <id> --force

# Cron jobs
createos cronjobs list --project <id>

# Simple GET cron job
createos cronjobs create --project <id> --environment <id> \
  --name "Cleanup job" --schedule "0 * * * *" \
  --path /api/cleanup --method GET

# POST cron job with headers and JSON body
createos cronjobs create --project <id> --environment <id> \
  --name "Webhook" --schedule "*/5 * * * *" \
  --path /api/hook --method POST \
  --header "Authorization=Bearer token" --header "X-Source=cron" \
  --body '{"event":"tick"}'

# Update HTTP settings (headers and body preserved if omitted)
createos cronjobs update --project <id> --cronjob <id> \
  --path /api/hook --method POST \
  --header "Authorization=Bearer token" --body '{"event":"tick"}'

createos cronjobs get --project <id> --cronjob <id>
createos cronjobs delete --project <id> --cronjob <id> --force

# Sandboxes
createos sandbox create --shape s-1vcpu-1gb --name my-box --ssh-key ~/.ssh/id_ed25519.pub
createos sandbox create --shape s-1vcpu-512mb --ingress --auto-pause 1h
createos sandbox list
createos sandbox list --all
createos sandbox list --status paused --quiet | xargs createos sandbox rm --force
createos sandbox get <id>
createos sandbox exec my-box -- uname -a
createos sandbox exec my-box --stream -- pip install requests
createos sandbox shell my-box
createos sandbox shell my-box --ssh
createos sandbox process run my-box -- npm test
createos sandbox process start my-box -- python -m http.server 8000
createos sandbox process shell my-box
createos sandbox process attach my-box proc_abc123
createos sandbox process attach my-box        # pick a running process or shell session
createos sandbox process ps my-box
createos sandbox process input my-box proc_abc123 --text "hello\n"
createos sandbox process signal my-box proc_abc123 SIGINT
createos sandbox process wait my-box proc_abc123 --all
createos sandbox process stop my-box proc_abc123 --grace 1s
# Inside a managed shell session, the fixed bottom bar shows active shortcuts.
# detach closes the local attach; new creates a shell and switches;
# switch opens the process picker; `exit` closes the current shell.
createos sandbox push my-box ./script.py /root/script.py
createos sandbox pull my-box /root/output.csv ./output.csv
createos sandbox tunnel my-box --local 8080 --remote 8000
createos sandbox pause my-box
createos sandbox resume my-box
createos sandbox fork my-box
createos sandbox edit my-box --ingress on
createos sandbox edit my-box --auto-pause 30m
createos sandbox rm my-box --force
createos sandbox shapes
createos sandbox rootfs

# Sandbox sync
createos sandbox sync my-box --local ~/work/project --remote /root/work
createos sandbox sync my-box --exclude '*.log' --exclude node_modules  # skip files (repeatable)
createos sandbox sync my-box --mode one-way   # push-only: laptop wins, keep extra remote files
createos sandbox sync my-box --mode mirror    # make sandbox identical, delete extra remote files
createos sandbox sync my-box --quiet          # run silently until Ctrl+C

# Sandbox disks
createos sandbox disk create my-data --bucket my-bucket --endpoint https://s3.amazonaws.com \
  --access-key AKID... --secret-key ...
createos sandbox disk ls
createos sandbox disk attach my-box my-data /mnt/data
createos sandbox disk detach my-box my-data /mnt/data --yes
createos sandbox disk rm my-data --yes

# Sandbox networks
createos sandbox network create my-net
createos sandbox network ls
createos sandbox network attach my-net my-box
createos sandbox network detach my-net my-box --yes
createos sandbox network rm my-net --yes

# Sandbox firewall
createos sandbox firewall show my-box
createos sandbox firewall set my-box pypi.org github.com
createos sandbox firewall clear my-box --yes

# Sandbox templates (custom images)
createos sandbox template submit my-rails -f Dockerfile
createos sandbox template ls
createos sandbox template logs my-rails --follow
createos sandbox template rm my-rails --yes

# Webhooks
createos webhooks list
createos webhooks get --endpoint <id>
createos webhooks create --url https://example.com/webhook
createos webhooks create --url https://example.com/webhook \
  --event sandbox.create --event sandbox.destroy
createos webhooks suspend --endpoint <id>
createos webhooks resume --endpoint <id>
createos webhooks delete --endpoint <id> --force

# Templates
createos templates use --template <id> --yes

# VMs
createos vms list
createos vms get --vm <id>
createos vms deploy --zone nyc3 --size 1 --name "my-vm" --ssh-key "ssh-ed25519 ..."
createos vms reboot --vm <id> --force
createos vms terminate --vm <id> --force
createos vms resize --vm <id> --size 1

# OAuth clients
createos oauth-clients list
createos oauth-clients create \
  --name "My App" \
  --redirect-uri https://myapp.com/callback \
  --app-url https://myapp.com \
  --policy-url https://myapp.com/privacy \
  --tos-url https://myapp.com/tos \
  --logo-url https://myapp.com/logo.png
createos oauth-clients instructions --client <id>
createos oauth-clients delete --client <id> --force

# Me
createos me oauth-consents list
createos me oauth-consents revoke --client <id> --force

JSON output and piping

All list and get commands output JSON automatically when stdout is a pipe, so | jq works without any flags:

createos projects list | jq '.[].id'
createos deployments list --project <id> | jq '.[] | select(.status == "running")'
createos cronjobs list --project <id> | jq '.[] | {id, name, schedule}'
createos vms list | jq '.[].extra.ip_address'
createos webhooks list | jq '.[].url'

To force JSON output in a TTY, use --output json (or -o json):

createos projects get --project <id> --output json
createos environments list --project <id> -o json

Options

Flag	Description
`--output, -o <fmt>`	Output format: `json` or `table` (default). Auto-json when piped.
`--debug, -d`	Print HTTP request/response details (token is masked)
`--api-url`	Override the API base URL
`--sandbox-api-url`	Override the sandbox API base URL
`--sandbox-gateway`	SSH gateway address (`host:port`) used by `sandbox shell --ssh`

Security

Your API token is stored at ~/.createos/.token with 600 permissions (readable only by you).
OAuth session tokens are stored at ~/.createos/.oauth with 600 permissions (readable only by you).
Debug mode masks your token in output — only the first 6 and last 4 characters are shown.
Never share your token or commit it to version control.

Name		Name	Last commit message	Last commit date
.github		.github
cmd		cmd
internal		internal
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.pre-commit-config.yaml		.pre-commit-config.yaml
.secrets.baseline		.secrets.baseline
.tool-versions		.tool-versions
CLAUDE.md		CLAUDE.md
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh
main.go		main.go

Navigation Menu

Uh oh!

Repository files navigation

CreateOS CLI

Installation

macOS & Linux — install script (recommended)

macOS & Linux — Homebrew

Nightly

Pin a specific version

Upgrade

Build from source

Contributing

Pre-commit hooks

Getting started

Commands

Authentication

Projects

Deploy

Deployments

Environments

Environment Variables

Domains

Cron Jobs

Templates

VMs

Sandboxes

Webhooks

Quick Actions

OAuth Clients

Me

Other

Non-interactive / CI usage

JSON output and piping

Options

Security

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

CreateOS CLI

Installation

macOS & Linux — install script (recommended)

macOS & Linux — Homebrew

Nightly

Pin a specific version

Upgrade

Build from source

Contributing

Pre-commit hooks

Getting started

Commands

Authentication

Projects

Deploy

Deployments

Environments

Environment Variables

Domains

Cron Jobs

Templates

VMs

Sandboxes

Webhooks

Quick Actions

OAuth Clients

Me

Other

Non-interactive / CI usage

JSON output and piping

Options

Security

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages