Documentation / CLI

Darwa CLI reference

Create projects, choose a GitHub repository, add services, and deploy from the same terminal where you write code. Browser authorization keeps passwords out of the CLI.

CLI 0.2.0Node.js 20+macOS + LinuxUpdated 13 Aug 2026

Install

Homebrew is the primary installation path on macOS. The release tarball is available when Homebrew is not installed.

terminal

# Homebrew
brew install haqiq-app/tap/darwa

# Upgrade later
brew update && brew upgrade darwa

# Alternative: install the signed release through npm
npm i -g https://github.com/haqiq-app/darwa-cli/releases/download/v0.2.0/darwa-cli-0.2.0.tgz

darwa --version

Sign in

darwa login opens a one-time approval page in your browser. After approval, the terminal stores a revocable access token—not your password.

terminal

darwa login
darwa whoami

# Local development API
darwa login --api http://localhost:8000/api/v1

darwa logout

How resources fit together

A project organizes related services. A service is the runnable website, API, worker, or hosting instance. GitHub is one possible source; local uploads use darwa deploy.

WorkspaceYour Darwa account and team boundary.

ProjectGroups production, preview, and related services.

ServiceA runnable app with source, runtime, region, and URL.

DeploymentOne immutable build and release of a service.

resource model

Workspace
└── Project: storefront
    ├── Service: frontend     ← GitHub acme/storefront
    ├── Service: checkout-api ← GitHub acme/checkout
    └── Deployments           ← builds, logs, releases

Projects

Command	Scope	What it does
darwa projects list	workspace	List projects with service, live, environment, and region totals
darwa projects create <name>	workspace	Create an empty project container
darwa projects show <slug>	project	Show the project and every service inside it
darwa projects delete <slug> --yes	project	Delete the project and all services it contains

terminal

darwa projects create Storefront
darwa projects list
darwa projects show storefront

# Machine-readable output
darwa projects list --json

GitHub repositories

Connect once, then list every repository available to the installed GitHub app. Private repository names are shown only to your authenticated workspace.

Command	Scope	What it does
darwa github status	workspace	Show the connected GitHub account
darwa github connect	workspace	Open GitHub authorization in the browser
darwa github repos	source	List repositories, visibility, default branch, and language
darwa github disconnect --yes	workspace	Remove the workspace source connection

terminal

darwa github connect
darwa github repos

REPOSITORY          VISIBILITY  BRANCH  LANGUAGE
------------------  ----------  ------  ----------
acme/storefront      private     main    TypeScript
acme/checkout-api    private     main    Python

Services

Create a service from an exact owner/repository name. Passing --project attaches it to the project shown in the dashboard.

Command	Scope	What it does
darwa services list	workspace	List all deployable services
darwa services list --project <slug>	project	List only services in one project
darwa services create <name> --repo <owner/repo>	source	Create a GitHub-backed web service
darwa services show <slug>	service	Show runtime, source, status, region, and URL
darwa services delete <slug> --yes	service	Delete one service and its runtime resources

terminal

darwa services create Frontend \
  --repo acme/storefront \
  --project storefront \
  --branch main \
  --runtime node \
  --region us-east

darwa services list --project storefront
darwa services show frontend

Billing

Creating a paid runtime service requires an available service subscription or billing authorization. The CLI returns the same actionable billing error as the dashboard.

Local website deploys

Run from a website directory to detect the runtime, package source, upload it, and wait for the service to become live. Existing darwa.json configuration is reused.

terminal

cd ./storefront
darwa deploy

# Deploy to an existing service
darwa deploy . --project storefront-web

# Queue without waiting for the final status
darwa deploy . --no-wait

Configuration and automation

Location	Purpose	Safe to commit?
~/.config/darwa/config.json	API endpoint and encrypted-session access token permissions	No
darwa.json	Links a local directory to its Darwa service slug	Yes
.darwaignore	Excludes paths from local deployment archives	Yes

Use --json on list and show commands for scripts. DARWA_API_URL, DARWA_WEB_URL, and DARWA_CONFIG_DIR can override CLI defaults.