Cloudgate CLI: deploy a folder from your terminal

Q: Can I use the CLI with a self-hosted Cloudgate?

Yes. Run cloudgate login --instance your-console-address. The CLI can be logged in to several Instances at once; cloudgate instance use switches between them. See how to self-host Cloudgate.

Q: Does the CLI create the app for me?

It can create the Project. A first cloudgate deploy in a folder with no link offers Create a new Project: it asks the name and where its apps run (a ready Server, or a Cloud account and region), makes the Project with a production Environment, and saves a starter cloudgate.yaml in the folder. Add your apps there and run cloudgate deploy again. To deploy one app into an existing Project, make the Application in the console first.

Run one command in your project folder and Cloudgate uploads it, builds it and follows the build log until it is live. The same commands work in a CI job with a key.

Install the CLI View on npm

~/my-app

$ npm install -g @octabyte-io/cloudgate@next
$ cloudgate login
  Approve code QXRT-7PLM in the console
$ cd my-app
# uploads this folder, builds it, follows the log
$ cloudgate deploy
  Uploading 214 files (skipping .env and .git)
  Building with Nixpacks
  Deployment done
# running? which address? which Deployment?
$ cloudgate status
  web  running  shop.example.com

The CLI is a beta. The current release, 0.0.2-beta.3, is on npm's next tag: npm install -g @octabyte-io/cloudgate@next. The latest tag (0.0.1) is a placeholder. Commands and flags may still change before 1.0; each beta is listed in the Cloudgate changelog, and the CLI's source is in the Cloudgate repository.

How do you deploy a folder with the Cloudgate CLI?

Four steps. You need Node 22 or newer and a Cloudgate account. Deploy into an Application made in the console, or let the first deploy make a new Project.

Install it from npm
The package is @octabyte-io/cloudgate; the command it installs is cloudgate. Install the beta from the next tag: the latest tag still holds a placeholder.
```
npm install -g @octabyte-io/cloudgate@next
```
Log in through your browser
The CLI prints a link and a code. Open the link on any device, check the code matches and approve it in the console. This computer then gets a Personal key that ends in 90 days, kept in the system keychain. For a self-hosted Cloudgate, give its address.
```
cloudgate login
cloudgate login --instance cloud.example.com   # a self-hosted console
```
Deploy the current folder
The first time, it asks which Project the folder belongs to (or makes a new one), then whether it is one app or the whole Project, and saves that link in .cloudgate/ (added to your .gitignore). It waits for any build already running, uploads, then follows the Deployment log and exits 0 only if the Deployment is done.
```
cloudgate deploy
cloudgate deploy --env production   # the same Service in another Environment
```
Check it is running
Status shows whether it runs, its Domains and its latest Deployment. Logs prints what it writes.
```
cloudgate status
cloudgate logs -f
```

What does cloudgate deploy upload?

The folder as it is on your disk, uncommitted changes included, minus anything that should not leave your machine.

Uploaded: Every file in the linked folder, or the current folder when nothing is linked yet, whether committed or not.
Left out by your ignore files: Anything any .gitignore or a .cloudgateignore lists. Both use the same syntax, and ! brings a file back.
Always left out: .git, .cloudgate, and .env files except .env.example. Put secrets in with cloudgate vars set KEY.
Only what changed, after the first time: Each deploy compares the folder with the Instance file by file (SHA-256) and uploads only new and changed files; files you deleted are deleted there too. --full sends every file. This needs an Instance at version 0.2.0 or newer; an older one simply gets the full upload.
Warned about: Symlinks are skipped with a warning, and an upload whose zip is over 100 MB names its biggest folders before it goes.

How do you deploy a whole Project from one folder?

Make the folder a Project folder, usually a monorepo's root. Its cloudgate.yaml describes every app, and one cloudgate deploy plans the change, then builds each app from its own subfolder. New in 0.0.2-beta.3.

Link the whole Project
It asks for the Organization, Project and Environment, never a Service, and saves the Project config here as your working copy.
```
cloudgate link --whole-project
```
Edit cloudgate.yaml
Give each app a subfolder as its source. cloudgate config pull fetches the current config again when a teammate has changed it.
Plan, then deploy
You see what each Environment's Plan creates, changes and destroys, and it applies on a yes. Destroying a Service asks you to type its Config name. Then every app built from a subfolder is uploaded, built and followed to its end.
```
cloudgate config plan   # the plan alone
cloudgate deploy        # the plan, then every app
```

~/shop

shop/
cloudgate.yaml
apps/web/
apps/api/
.cloudgate/

# Cloudgate keeps this Project's config;
# this file is your working copy.
version: 1
services:
  web:
    kind: web
    source: { folder: apps/web }
  api:
    kind: web
    source: { folder: apps/api }

A first deploy asks: In a folder with no link, cloudgate deploy asks which Project, or offers to create one, then whether this is one app or the whole Project.
Edits never cross: If the Project config has moved on since your copy, the plan is refused and nothing is sent; config pull brings your copy up to date.
Only apps from a subfolder are built: Apps from a repository or an image, databases and buckets are listed as skipped. --service deploys one app only.
Safe without a terminal: In CI, --yes applies a plan, but still refuses one that destroys a Service or makes a major upgrade.

Which commands does the CLI have?

Every command explains itself with --help. Several take --json for scripts, and every one that acts on a Service takes --org, --project, --env and --service.

$ cloudgate status
Service      web
State        running
Domains      shop.example.com
Deployment   done

This folder

cloudgate deploy: Upload what changed in this folder and deploy it, then follow the Deployment log until it ends. --full uploads every file.
cloudgate status: Show the Service, whether it is running, its Domains and its latest Deployment.
cloudgate logs: Show the Service's last 100 log lines; -f keeps following, --deployment shows a build log.
cloudgate vars list | set | unset: List, set and unset the Service's variables. Values are never printed.
cloudgate link: Link this folder to a Service, so later commands know where to go.
cloudgate unlink: Remove this folder's link. Nothing changes on the Instance.

$ cloudgate instance list
* cloudgate.octabyte.app
  cloud.example.com

Logging in

cloudgate login: Log in to an Instance through your browser. Add --instance <url> for a self-hosted one.
cloudgate whoami: Show who you are logged in as, where, and when your key ends.
cloudgate instance list: Show the Instances you are logged in to, marking the current one.
cloudgate instance use <url>: Switch the current Instance.
cloudgate logout: Log out and delete this computer's key on the Instance. --all logs out everywhere.

A Project folder

cloudgate link --whole-project: Link this folder to a whole Project and save its config here as cloudgate.yaml.
cloudgate config pull: Replace this folder's cloudgate.yaml with the Project config as Cloudgate holds it.
cloudgate config plan: Show what your cloudgate.yaml would create, change and destroy, and apply it on a yes.
cloudgate deploy: At the root: plan, then build every app the config builds from a subfolder.

Templates

cloudgate template try <folder>: Start a template's compose part on this computer's Docker, check each Domain answers, then remove it all. Values come from test-values.yaml.
cloudgate template check <path>: Check templates as Cloudgate will read them, without any request.
cloudgate template pack <folder> <out>: Build the catalogue.zip a templates release publishes.

How do you deploy from CI?

Use a Personal key instead of logging in. Make one in the console, store it as a secret in your CI, and set it as CLOUDGATE_KEY.

A CI job cannot answer questions, so name the target with variables or flags. Add --switch-source if the Service used to deploy from git or an image, and --detach --json to queue the Deployment and move on. A key from CLOUDGATE_KEY is never written to disk.

.github/workflows/deploy.ymlAny CI job

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @octabyte-io/cloudgate@next
      - run: cloudgate deploy
        env:
          CLOUDGATE_KEY: ${{ secrets.CLOUDGATE_KEY }}
          CLOUDGATE_PROJECT: shop
          CLOUDGATE_ENV: production
          CLOUDGATE_SERVICE: web

# in your CI job
export CLOUDGATE_KEY=<Personal key from your secrets>
export CLOUDGATE_PROJECT=shop
export CLOUDGATE_ENV=production
export CLOUDGATE_SERVICE=web

npm install -g @octabyte-io/cloudgate@next
cloudgate deploy --switch-source

Not working in a terminal?

The CLI is one of three ways in. The other two reach the same Projects and Services.

Put an AI-built app online without a terminal
Pick a template or point Cloudgate at your folder, get a server, press Deploy.
Let your AI agent deploy over MCP
An agent gets its own member account, key and grant, and every call it makes is audited.
Start from an app template
Deploy a ready-made app, such as n8n, Ghost or Uptime Kuma, from the console.

The CLI works with the hosted console and with a self-hosted Cloudgate. See what the hosted plans cost.

Questions people ask

Which version of Node does the Cloudgate CLI need?

Node 22 or newer. The command refuses to start on an older Node and says so.

Does cloudgate deploy upload my .env file?

No. .env and .env.* files are left out (except .env.example), and so is anything your .gitignore or a .cloudgateignore lists. Put secrets in with cloudgate vars set KEY, which asks for the value without showing it.

Can I use the CLI with a self-hosted Cloudgate?

Yes. Run cloudgate login --instance your-console-address. The CLI can be logged in to several Instances at once; cloudgate instance use switches between them. See how to self-host Cloudgate.

Does the CLI create the app for me?

It can create the Project. A first cloudgate deploy in a folder with no link offers Create a new Project: it asks the name and where its apps run (a ready Server, or a Cloud account and region), makes the Project with a production Environment, and saves a starter cloudgate.yaml in the folder. Add your apps there and run cloudgate deploy again. To deploy one app into an existing Project, make the Application in the console first.

Does cloudgate deploy upload the whole folder every time?

No. From version 0.0.2-beta.3 it uploads only the files that are new or changed since the last upload, and deletes on the Instance the files you deleted. Run cloudgate deploy --full to send every file. An Instance older than 0.2.0 always gets the full upload.

How do I deploy from CI without logging in?

Make a Personal key in the console, store it as a secret, and set CLOUDGATE_KEY in the job. Name the target with CLOUDGATE_ORG, CLOUDGATE_PROJECT, CLOUDGATE_ENV and CLOUDGATE_SERVICE, since a CI job cannot answer questions.

Deploy your first folder today

Start a 30-day free trial, make an Application in the console, then run cloudgate deploy from your project folder.

Start free trial Deploy a template

Cloudgate CLI: deploy a folder from your terminal

How do you deploy a folder with the Cloudgate CLI?

Install it from npm

Log in through your browser

Deploy the current folder

Check it is running