Documentation / CLI
Darwa CLI
Everything currently available from the Darwa terminal client—using real commands and the same plans and permissions enforced by the dashboard.
CLI 0.2.0Node.js 20+macOS + LinuxUpdated 7 Sep 2026
Install
Install with Homebrew on macOS, or use the published npm release on macOS and Linux.
terminal
brew install haqiq-app/tap/darwa
# Alternative release
npm i -g https://github.com/haqiq-app/darwa-cli/releases/download/v0.2.0/darwa-cli-0.2.0.tgz
darwa --version
darwa update --check
darwa update
Secure sign-in
darwa login opens the Darwa approval page and returns a one-time authorization code to a random 127.0.0.1 port. PKCE and state verification bind that response to the CLI that started the request. Your password never enters the terminal.
| Command | Scope | What it does |
|---|
| darwa login | same device | Open browser authorization with a protected localhost callback |
| darwa login --remote | another device | Use a separate one-time browser code and secure WebSocket approval |
| darwa login --force | current device | Replace an existing CLI session |
| darwa whoami | account | Show the account connected to this terminal |
| darwa logout | current device | Revoke the local session and remove its saved credential |
terminal
darwa login
# Browser is on another device
darwa login --remote
# Replace the current session
darwa login --force
SecurityCLI sessions expire after six hours and appear in Dashboard → Settings → Security, where they can be revoked at any time. Authorization codes are short-lived, single-use, and stored only as hashes.
AI Deployment Copilot
Live inventory answers are free. Model-backed conversation and deployment analysis are opt-in: the CLI asks before the first charge, non-interactive use requires --yes, and every paid reply prints the exact charge and remaining wallet balance. Darwa AI is read-only and receives only a bounded, sanitized workspace snapshot.
| Command | Scope | What it does |
|---|
| darwa ai chat | live workspace | Open an interactive assistant with resource-aware selection menus |
| darwa ai chat "<question>" | live workspace | Ask one question from a terminal or script |
| darwa ai models | model catalog | Compare available models and see the workspace default |
| darwa ai model select | AI credits | Select the default model used by workspace AI operations |
| darwa diagnose <service> | latest deployment | Explain the likely cause, evidence, and recommended actions |
| darwa ai diagnose <service> | latest deployment | Run the same read-only diagnosis through the AI command group |
| darwa deploy --ai | failed deployment | Offer diagnosis only if the new deployment fails |
| darwa ai workspace | workspace telemetry | Prioritize reliability, security, capacity, performance, and cost signals |
| darwa ai credits | workspace wallet | Show balance, lifetime usage, and recent credit activity |
| darwa ai usage --days 30 | workspace wallet | Show requests, tokens, models, and credit cost for 7–90 days |
terminal
darwa ai chat
you › Are any Frontend Cloud builds failing?
darwa deploy . --project storefront --ai
# CI: explicit consent without an interactive prompt
darwa deploy . --project storefront --ai --yes
darwa diagnose storefront
darwa ai workspace
darwa ai credits
darwa ai usage --days 30
Read onlyDiagnosis never edits source, changes a paid plan, executes commands, or redeploys. Environment values are redacted before logs reach the model; only configured variable names are included.
Active product coverage
| Product | CLI workflow | AI-credit behavior |
|---|
| Web Hosting | Plans, websites, terminal, and File Manager | Deployment diagnosis when backed by a runtime project |
| Web Services | Projects, services, GitHub, and deploys | Sanitized deployment diagnosis |
| Frontend Cloud | Deploy to an existing frontend service | Failed build diagnosis |
| Databases | Inventory and PostgreSQL migration | Wallet is shared with dashboard database AI |
| AI Agents | Catalog, plans, slots, and installation | Wallet remains separate from agent hosting plans |
| AI Credits | Balance, activity, and usage reporting | Exact per-request charge and remaining balance |
Plans through the CLI
The CLI reads the current catalog from Darwa instead of embedding prices or capacity. Checkout is created by the backend and completed on Stripe. Ownership, available slots, plan compatibility, and capacity are checked again before provisioning.
| Command | Scope | What it does |
|---|
| darwa hosting plan | Web Hosting | Select and purchase an available Web Hosting plan |
| darwa agents catalog | AI Agent catalog | Show verified agents and each recommended plan |
| darwa agents catalog --plan <code> | AI Agent plan | Check which agents fit a specific current plan |
| darwa agents plan --plan <code> | AI Agent plan | Open checkout for a new compatible agent slot |
| darwa agents plan --term 1|12|24 | billing term | Choose a supported billing term |
terminal
darwa hosting plan
darwa agents catalog
darwa agents catalog --plan individual
darwa agents plan --plan startup --term 12
# Print checkout without opening it
darwa agents plan --plan startup --term 12 --no-browser --no-wait
Web Hosting
| Command | Scope | What it does |
|---|
| darwa hosting | workspace | List plans and websites, then open the interactive hosting console |
| darwa hosting add | available plan | Create a website in an unused hosting slot |
| darwa hosting plan | billing | Purchase another hosting plan through secure checkout |
| darwa shell <website> | one website | Open an approved 15-minute server terminal |
| darwa files <website> | one website | Open File Manager with a scoped 15-minute grant |
AI agents
| Command | Scope | What it does |
|---|
| darwa agents list | workspace | Show purchased plans, free slots, and installed agents |
| darwa agents catalog | catalog | List verified agents and capacity requirements |
| darwa agents install <agent> | agent slot | Validate compatibility and provision one verified agent |
| darwa agents plan | billing | Purchase an AI Agent plan |
terminal
darwa agents list
darwa agents catalog --plan individual
darwa agents install n8n --name automation --slug automation
Resources and databases
| Command | Scope | What it does |
|---|
| darwa list | workspace | Show hosting purchases, domains, databases, and applications |
| darwa list --json | workspace | Return the same inventory as machine-readable JSON |
| darwa databases list | workspace | List managed databases |
| darwa databases migrate [directory] | database | Discover a local PostgreSQL source and upload a private dump |
terminal
darwa list --all
darwa databases list
darwa databases migrate . --to production-db --replace
Projects and services
| Command | Scope | What it does |
|---|
| darwa projects list | workspace | List projects and their service totals |
| darwa projects create <name> | workspace | Create a project |
| darwa projects show <project> | project | Inspect one project and its services |
| darwa projects delete <project> --yes | project | Delete a project after explicit confirmation |
| darwa services list | workspace | List deployable services |
| darwa services create <name> --repo <owner/repo> | project | Create a GitHub-backed service |
| darwa services show <service> | service | Inspect runtime, source, region, status, and URL |
| darwa services delete <service> --yes | service | Delete one service after explicit confirmation |
GitHub
| Command | Scope | What it does |
|---|
| darwa github status | workspace | Show the connected GitHub account |
| darwa github connect | workspace | Open GitHub authorization |
| darwa github repos | source | List repositories available to the installed GitHub app |
| darwa github disconnect --yes | workspace | Remove the source connection |
Local deploys
Run from a website directory. Darwa packages the source, enforces archive limits, uploads it privately, and waits for the deployment unless --no-wait is supplied.
terminal
darwa deploy
darwa deploy . --project storefront-web
darwa deploy . --clear-cache --no-wait
Configuration
| Location | Purpose | Commit? |
|---|
| ~/.config/darwa/config.json | Local API endpoint and revocable CLI session | No |
| darwa.json | Links a directory to a Darwa project or service | Yes |
| .darwaignore | Excludes files from deployment archives | Yes |
Use DARWA_API_URL, DARWA_WEB_URL, and DARWA_CONFIG_DIR only when overriding defaults for development or automation.