DeployOn CLI — Full Guide

English instructions for users and AI agents to install the CLI and manage DeployON apps.

Console: https://console.deployon.pro
npm: @deployon/cli
This repo: https://github.com/proservice-dev/deployon

Install only via npm. Do not clone private platform repositories for end users.

---

Agent Prompt (copy-paste)

Help the user install the DeployOn CLI and connect their local project.

Platform: https://console.deployon.pro
Docs: https://github.com/proservice-dev/deployon/blob/main/docs/CLI.md
Package: @deployon/cli on the public npm registry

CRITICAL:
- Do NOT clone private DeployOn/Docklet platform repositories.
- Do NOT build the CLI from source for the user.
- Install only via: npm install -g @deployon/cli

=== Install (Node.js 20+) ===

All OS:
  npm install -g @deployon/cli
  deployon --version

If npm install returns 404:
  Wait 1–5 minutes after a fresh publish, then:
  npm cache clean --force
  npm install -g @deployon/cli@latest --registry=https://registry.npmjs.org/
  Verify with: npm view @deployon/cli version

=== Windows PowerShell Execution Policy (common) ===

If you see:
  "cannot be loaded because running scripts is disabled on this system"
  (npm.ps1 or deployon.ps1)

This is Windows PowerShell policy — NOT a CLI bug. Fix in order:

  1) Permanent (recommended):
     Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
     Open a NEW PowerShell window
     deployon --version

  2) Session-only:
     Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
     deployon --version

  3) Without changing policy:
     npm.cmd install -g @deployon/cli
     deployon.cmd --version
     Or use Command Prompt (cmd.exe) instead of PowerShell — .cmd shims work there.

Check policy: Get-ExecutionPolicy -List

=== Context (after login) ===

  deployon project ls
  deployon project select              # or: deployon project use <name>
  deployon deployment ls
  deployon deployment select
  deployon context
  deployon stats
  deployon project stats
  deployon deployment stats
  deployon deployment domain ls
  deployon dns

Lifecycle (optional name; uses active context if omitted):
  deployon project|deployment start|suspend|restart|redeploy|delete [-y]

=== Auth ===

  deployon login                 # browser → https://console.deployon.pro/cli/authorize (Team Owner)
  deployon login --token dklt.*  # CI / headless (Dashboard → API tokens)

=== Connect (inside the user's app directory) ===

  deployon init --connect --create   # new platform project
  deployon connect                   # existing project (git remote match)

=== Deploy ===

  deployon deploy --push --wait      # git push + build
  deployon deploy --local --wait     # tarball upload (no git required)

=== Success criteria ===

  deployon --version works
  deployon whoami shows the user
  deployon.json exists in the project
  deploy ends healthy (or user can open dashboard)

---

1. Prerequisites

Requirement	Detail
Account	https://console.deployon.pro
Team	Projects belong to a team
Node.js	20+
Git	Recommended for deploy --push
CLI	npm install -g @deployon/cli

---

2. Install

npm install -g @deployon/cli
deployon --version

Windows: “running scripts is disabled”

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Open a new PowerShell window, then run deployon --version.

Without changing policy:

npm.cmd install -g @deployon/cli
deployon.cmd --version

Or use Command Prompt (cmd.exe).

---

3. Authentication

Browser login (default)

deployon login

1. Terminal shows a code (e.g. ABCD-1234)
2. Browser opens https://console.deployon.pro/cli/authorize
3. Team Owner approves
4. deployon whoami should show the email

API token (CI / headless)

1. Dashboard → Settings → API tokens (Owner creates)
2. Token format: dklt.<id>.<secret> (shown once)

deployon login --token dklt.xxxxx.yyyyy
deployon whoami

---

4. Context

State is stored in ~/.deployon/config.json.

Command	Description
deployon context	Show active project & deployment
deployon project select [name]	Set active project (use alias; interactive if omitted)
deployon deployment select [name]	Set active deployment

Note: A deployment in this CLI is an application (platform service). Build runs use deployon deploy / deployon logs.

---

5. Projects

Command	Aliases	Description
deployon project list	ls	List projects
deployon project select [name]	use	Set active project
deployon project stats [name]		Project usage metrics
deployon project start [name]	resume	Start all apps
deployon project suspend [name]	pause, stop	Stop all apps
deployon project restart [name]		Restart all apps
deployon project redeploy [name]		Rebuild/redeploy all apps
deployon project delete [name]	remove, rm	Delete project (-y skips confirm)

---

6. Deployments (apps)

Requires an active project (deployon project select).

Command	Aliases	Description
deployon deployment list	ls	List apps in active project
deployon deployment select [name]	use	Set active app
deployon deployment domain list [name]	ls	Domains for app
deployon deployment dns [name]	deployon dns	DNS / SSL info
deployon deployment stats [name]		Live metrics
deployon deployment start [name]	resume	Start app
deployon deployment suspend [name]	pause, stop	Stop app
deployon deployment restart [name]		Rolling restart
deployon deployment redeploy [name]		Trigger build+deploy
deployon deployment delete [name]	remove, rm	Delete app (-y)

---

7. Account stats

deployon stats
deployon stats --team <id>

---

8. Connect a local git project

cd /path/to/my-app
git remote -v
deployon init --connect --create

Or link an existing dashboard project:

deployon connect

Creates deployon.json with project/service IDs.

---

9. Deploy

Git workflow

git add .
git commit -m "Deploy to DeployOn"
deployon deploy --push --wait

Without git (tarball)

deployon deploy --local --wait

Limit: 100MB. Excluded: .git, node_modules, .next, dist, build.

---

10. Logs and ops

deployon status
deployon logs --follow
deployon logs --download app.log
deployon cancel
deployon rollback

Dashboard: https://console.deployon.pro

---

11. Troubleshooting

Symptom	Fix
running scripts is disabled	Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, or use npm.cmd / deployon.cmd / CMD
Missing token after login	deployon login --token dklt.* or re-login
deployon: command not found	Reinstall; ensure npm global bin is on PATH (npm prefix -g)
404 on npm install	Wait for registry; npm cache clean --force; npm install -g @deployon/cli@latest
No project selected	deployon project ls then deployon project select
Permission denied	Token must be created by Team Owner; Developer+ role required
No git remote	git remote add origin <url> or deployon deploy --local

---

12. Quick cycle (Windows)

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
# open a new PowerShell window

npm install -g @deployon/cli
deployon --version

deployon login
deployon project select
deployon deployment select
deployon deployment stats

---

Global flags

• --json — machine-readable output
• --verbose / --debug
• --project / --service / --team — overrides for link/deploy flows