@octabyte-io/cloudgate
v0.1.1
Published
Deploy a folder to Cloudgate from your terminal.
Readme
Cloudgate CLI
Deploy a folder to Cloudgate from your terminal. Published to npm as @octabyte-io/cloudgate; the command is cloudgate. Needs Node 22 or newer.
npm install -g @octabyte-io/cloudgate
cloudgate login --instance cloud.acme.dev # approve the code in the console
cloudgate whoami
CLOUDGATE_KEY=<a Personal key made in the console> cloudgate whoami # in CIcloudgate --help lists the commands; cloudgate <command> --help explains one.
Working on it
pnpm --filter @octabyte-io/cloudgate test # unit lane: pure rules, no server
pnpm --filter @octabyte-io/cloudgate build # bundles dist/cloudgate.mjs
node cli/bin/cloudgate.js --help # run the buildThe one e2e suite runs the built command against the backend harness:
cd backend && npx jest --config ./test/jest-e2e.json --runTestsByPath test/cli/cli.e2e-spec.tsEvery CLI ticket adds its walk to that suite (backend/test/cli/cli.e2e-spec.ts, helpers in cli-harness.ts) instead of adding a suite. The accepted help text locks command names, flags, variables and exit codes.
Layout
| Path | What it is |
|---|---|
| bin/cloudgate.js | The launcher npm links. Refuses Node < 22, then loads the bundle. A per-platform file arriving through optionalDependencies (ADR 0046) is looked for here first, later. |
| build.mjs | esbuild: one ESM file, api-schemas and zod bundled, version stamped from package.json. @napi-rs/keyring stays external: the package's one runtime dependency, optional and native. The backend's Template check is bundled from its source under the alias cloudgate-template-check, stamped with the backend's version, and its setup values and compose file preparation (templates/setup/cli-bundle.ts, for template try) under cloudgate-template-setup: the two exceptions ADR-0046 allows. |
| src/template-check.d.ts | The hand-written declaration of that alias, as far as template check, template pack and template try use it, and why it is not shared through api-schemas. |
| src/template-setup.d.ts | The same for cloudgate-template-setup, the backend's setup values and compose file preparation (backend/src/templates/setup/cli-bundle.ts), which template try prepares a Template with. |
| src/try-stack.ts | prepareStack: a Template's compose part as an Instance's stack folder holds it (the compose file, its .env, files/), made by the backend's own code, each Domain on a free 127.0.0.1 port; and the samples an ask input gets (randexp, bundled, for a pattern). |
| src/docker.ts | DockerRun, the one way the CLI reaches Docker (Invocation.docker, the docker on PATH unless given), and isDockerMissing. |
| src/template-folders.ts | templateFoldersAt: a template folder, or a folder of them, read as cg-templates holds them, so template check checks a folder exactly as template pack packs it. |
| src/run.ts | One whole run, with no process: argv, env and streams in, exit code out. Flag parsing and dispatch. main.ts wires it to the process. |
| src/commands/ | One file per command; commands/index.ts is the registry the overview help is built from. |
| src/terminal.ts | The output rule: colour, spinner, may we ask; and requireInputs, the missing-input refusal. |
| src/output.ts | The only way a command writes: data/json to stdout, note to stderr, withSpinner. |
| src/errors.ts | CliError, refusalFromResponse (an Instance's refusal → message, hint, exit code), reportError. |
| src/exit-codes.ts | The fixed exit codes. |
| src/instance.ts | chooseInstance, instanceAddress (the address rules) and instanceEndpoints. |
| src/instance-check.ts | checkInstance: the public "this is a Cloudgate" answer and the version floor, before any key is sent. |
| src/server-version.ts | MINIMUM_SERVER_VERSION and the semver compare. |
| src/api-client.ts | The hand-written client on api-schemas. |
| src/http.ts | What every request shares: reach (no redirect followed; "could not reach" when it never lands), USER_AGENT, parseJson, notUnderstood. |
| src/stopping.ts | Waiting and Ctrl-C: POLL_MILLISECONDS, abortOf, withInterrupts (a signal Ctrl-C aborts while some work runs). |
| src/credentials.ts | Where the key comes from: credentialFor (CLOUDGATE_KEY, else the saved login for the chosen Instance) and endedLogin, the refusal for a saved key an Instance no longer accepts. |
| src/logins.ts | loginStore: the saved logins and the current Instance (instances.json), their keys in the OS keychain (osKeychain) or a 0600 credentials.json. |
| src/folder-link.ts | The Folder link: findNearestLink, writeLink (with the .gitignore lines), removeLink, isProjectFolder (a link naming no Service, recording its workingCopy). |
| src/working-copy.ts | A Project folder's cloudgate.yaml (ADR-0080): downloadProjectConfig (refusing a repository-kept config), mayReplaceWorkingCopy (asks, or refuses without --yes), saveWorkingCopy (writes it and records its version and SHA-256 in the link), linkWholeProject (all of link --whole-project once the target is known, which a first deploy reuses), readWorkingCopy, workingCopyEdited, hashText, findProjectFolder (the nearest link, refused unless it names no Service). |
| src/plan-step.ts | runPlanStep: a Project folder's cloudgate.yaml sent as a whole-YAML edit naming its version, each Environment's Plan printed, and applied on a yes (each destroy and major upgrade typed by Config name; --yes refuses both), then the new version recorded; a run that applies nothing dismisses the plans it stored. config plan is this step alone; a root deploy runs it first. |
| src/target.ts | The shared target lookup: targetInputs (flag → variable → link), resolveTarget (id, then name; asks or refuses), resolveProjectTarget (the same, down to the Environment), TARGET_OPTIONS. |
| src/target-session.ts | connectToInstance (the first steps every command takes), lookUpTarget (those plus the target), instanceCatalog, projectsInThisRepositoryFirst (the Project whose config this repository keeps listed first, for link and a first deploy), chooserFor, describeTarget. |
| src/service-status.ts | readServiceStatus: a Service's state, source, Domains and latest Deployment from its own kind's routes (/applications, /compose, /postgres, …), for status; kindRefusal, the one "Applications only" refusal deploy, vars and logs share. |
| src/prompt.ts | The terminal's questions (Prompter): a numbered pick (with an optional default an empty answer takes), a yes/no, a typed line (text, for a Config name config plan confirms or a new Project's name, with an optional default) and a hidden answer (secret, for vars set KEY), on node:readline. |
| src/upload-files.ts | Which files deploy uploads (selectUploadFiles: .git, .cloudgate, ignore files, .env, symlinks) and what it says about their size (summarizeUpload). |
| src/ignore-rules.ts | The .gitignore pattern syntax, read for .gitignore and .cloudgateignore alike. |
| src/zip.ts | packUpload: the zip the upload route reads (deflate, UTF-8 names, no Zip64). |
| src/deploy-steps.ts | What deploy does for one Application, shared by a deploy of one Service and a root deploy: untilNoBuildInProgress, uploadFiles (only the changed files, or every file, with a build path), startDeployment, watchBuild. |
| src/project-deploy.ts | deployProjectFolder: deploy in a Project folder (ADR-0080). runPlanStep, then the whole folder uploaded to each app the config (GET /environments/:id/config/sources) builds from a subfolder, each built and followed, one line per app at the end. |
| src/first-deploy.ts | A first deploy in a folder with no link, in a terminal and with no target flag or variable (asksFirstDeploy, askFirstDeploy): which Project (plus "Create a new Project"), then "One app or the whole Project?" (one app by default; one app only for a repository-kept config). |
| src/new-project.ts | createProjectHere: "Create a new Project" from a first deploy: the name, the Deploy target (a ready deploy Server or a Cloud account and region), then POST /projects, POST /environments (production) and the starter config (STARTER_PROJECT_CONFIG in api-schemas) as a whole-YAML edit, and linkWholeProject. A failure after the Project exists says what was made and how to finish or remove it. |
| src/deploy-guards.ts | What deploy checks before it uploads, as rules with no network: sourceVerdict (refuse, ask or go for a source switch), runningBuildVerdict (wait for a build in progress, or go ahead past a held or stuck one). |
| src/deployment-watch.ts | watchDeployment: follows a Deployment to its end, which GET /deployments/:id decides, never the stream. |
| src/runtime-log.ts | A Service's Runtime log (logs): readServerRuntimeLog over /docker-container-logs (follow=false without -f, ends on close code 4014) and readCloudRuntimeLog polling GET /applications/:id/runtime-log. |
| src/deployment-log-stream.ts | deploymentLogFollower over /listen-deployment, and SocketOpener (Node's WebSocket with upgrade headers). |
| src/git-origin.ts | The folder's origin repository and path, for listing its Project first in link. |
| src/config-dir.ts | configDir: the settings folder (CLOUDGATE_CONFIG_DIR, XDG, %APPDATA%). |
| src/update-notice.ts | The update notice: when it may show, the npm check, its state file. run starts it and prints it last. |
| scripts/release.ts | The release workflow's two decisions: tag against package.json version (and next or latest), and the version's CHANGELOG section. |
Releasing
.github/workflows/release-cli.yml publishes on a cli-v<version> tag; there is no other way a version reaches npm.
- On
main, setversionincli/package.jsonand move the CHANGELOG's Unreleased entries under a## <version>heading. git tag cli-v<version> && git push origin cli-v<version>.- Approve the run in the GitHub environment
npm.
The workflow fails before publishing when the tag and package.json disagree or the CHANGELOG has no section for the version, and runs this package's type-check, lint and tests (not the server's e2e). It publishes by npm trusted publishing, no token, and without a provenance statement, which npm accepts only from a public repository: a version with a prerelease part (0.2.0-beta.1) to the next dist-tag, any other to latest. Then, and only then, it makes a GitHub Release on the tag from that CHANGELOG section, marked pre-release for next. Check both decisions locally with node cli/scripts/release.ts check cli-v<version> and node cli/scripts/release.ts notes <version>.
The trusted publisher on npm (package Settings) names GitHub Actions, octabyte-io/cloudgate, the workflow file release-cli.yml and the environment npm; renaming the workflow file breaks publishing until that is changed too.
Decisions later commands follow
- The Instance address is the console's, the address a person types and pastes. REST is reached at
<instance>/backend/*, the console's own proxy to the API. WebSockets, which the console does not proxy, go to the API's own origin, which the public answer advertises asapiUrl(CLOUDGATE_API_URLon the server; null when unset): usecheckInstance(...).endpoints.websocket. Both mappings live only ininstanceEndpoints(src/instance.ts). The e2e harness puts a small stand-in for the console's/backendrewrite in front of the backend, so the CLI needs no test-only flag. - Every command that talks to an Instance takes the same steps first, through
connectToInstance(src/target-session.ts):chooseInstance→instanceAddress(url, { allowHttp })→ printUsing instance <url>→credentialFor→checkInstance({ address, fetch }), all before its first request carrying a key (and, fromloginon, before saving one).instanceAddressaddshttps://to a bare address, keeps only the origin, and refuses plainhttp://except forlocalhost/127.0.0.1or with--allow-http, with exit 2 (the address given is wrong, and nothing was asked yet).checkInstanceasksGET /backend/settings/aboutwith no key, and refuses with exit 1 an address that does not answer it (<url> is not a Cloudgate) or an Instance older thanMINIMUM_SERVER_VERSION(naming both versions). OnlylogoutpassesallowOlder: true. Compare Instance addresses only afterinstanceAddress, so a Folder link and a flag agree on spelling. --allow-httpis accepted by every command (a global flag inrun.ts), because every command applies the address rules. Onlylogin's help lists it, as the accepted help text does, and the refusal's hint names it. It is notlogin-only because a CI job never logs in: it runsdeployorlogswithCLOUDGATE_KEYagainst an Instance on a LAN address served over plainhttp://, and that command is the one that has to be told the address is meant.- Redirects are never followed, by the check or by
ApiClient(redirect: 'error'): a followed redirect would carryx-api-keyto wherever it pointed. - Raise
MINIMUM_SERVER_VERSIONin the CLI release that first needs a server change, to the server version that ships it. - Data on stdout, everything else on stderr, always through
Output. A--jsoncommand prints its one object only after every request has succeeded, so stdout is empty on any error. - Every failure is a
CliError, reported byreportErrorasError: <message>, then at most one hint line. The CLI's own refusals use the sameError:prefix as an Instance's, so there is one shape to grep for. - Branch on
code, never onmessage. An Instance's refusal keeps itscodeon theCliError(error.code), asdeployreadsDEPLOYMENT_IN_PROGRESS. 401 exits 3; every other refusal exits 1. A 403 gets "Ask an owner of for access." only when it carries no code (the role's refusal) or one of the*_ACCESS_NOT_GRANTEDcodes. This is the console's rule (ApiError.isUnnamedRefusal): a banned account or a removed member is also a 403, and no owner can fix those. PassorganizationNamein the client's refusal context when the command knows it. - Never ask without a terminal. Use
terminalMode().canAsk. When a command cannot ask,requireInputsrefuses with exit 2 and names the first missing flag and its variable. - A key from
CLOUDGATE_KEYis never written anywhere, andwhoami --jsonreports it askeyFrom: "env"; a saved login's as"login". - Saved logins live only in the
LoginStore(src/logins.ts,CommandContext.logins), one per Instance address asinstanceAddressspells it. Get a key throughcredentialFor. A client fromconnectToInstancebuilt on a saved login already forgets it on a 401 and refuses withendedLogin(exit 3), so no command handles an ended login itself.logoutis the one command that does not useconnectToInstance: it sends the saved key toDELETE /users/me/api-keys/<its keyId>(the one key route a key may use, on itself), then callslogins.forget(instance)whatever happened there. logoutalways leaves this computer clean. It checks the Instance withallowOlder: true(an old Instance can still end a login), deletes the key there, and forgets the login even when the Instance cannot be reached, is not a Cloudgate or refuses the delete; it then printsError: its key was not deleted on <instance>: …with a hint to delete it in the console, and exits 1. A 401 means the key had already ended, which is a clean logout (exit 0).--instanceis taken over a Folder link instead of being refused for disagreeing with it;--allis every saved login, carrying on past one that fails. Not logged in is exit 0, "nothing to do".logoutrefusesCLOUDGATE_KEY(exit 2). That key is never saved, so there is no login to forget, and deleting it on the Instance would break whatever else holds it (a CI secret): it is revoked in the console. With the variable set the run ignores saved logins, so logging out of one is refused rather than guessed at; unset it first.- Tests never touch a real keychain. The unit lane passes its own
Keychain; the e2e harness setsCLOUDGATE_NO_KEYCHAIN=1. That variable is an internal test and ops switch (keys go to the 0600credentials.json, as on a machine with no keychain, for a box where a keychain prompt is unwanted), not a documented option: it is deliberately not in--helpor the CHANGELOG.@napi-rs/keyringhas no install script, sopnpm-workspace.yamlneeds no entry for it. - Login is the device flow:
POST /backend/auth/device/code, thenPOST /backend/auth/device/tokeneveryintervalseconds, approved at the console's/device. The CLI prints<instance>/deviceitself, so the link is the address it checked. Login takes--instance, thenCLOUDGATE_INSTANCE, then the hosted Instance, never a link's or the current one. - The update notice never reaches npm in a test. It is off without an
updateStatestore in theInvocation(the unit lane passes none unless it tests the notice), and the e2e harness'srunCliruns with pipes andCLOUDGATE_NO_UPDATE_NOTIFIER=1. - A command that acts on a Service starts with
lookUpTarget(context, { choose })(src/target-session.ts): the nearest Folder link,connectToInstancewith it, then the target. It answers the Instance, the key, the link, theTarget(service.id,service.configName,service.kind, …) and a client already sendingx-organization-id. Passchoose: chooserFor(prompter)only whenout.mode.canAsk; without it a missing level exits 2 naming its flag. AddTARGET_OPTIONSto the command'soptions, and print where it goes withdescribeTarget. - The link fills a level only while the levels above it are the link's too; its Service Config name always applies. So
--env productionre-finds the linked Config name there (refusing, naming both, when it is missing), and--project otherdrops the link's Environment rather than looking an id up in the wrong Project. linkreads no existing link, for its answers or its Instance: it is the command that replaces one.- No value of a variable ever comes back (ADR 0019).
varsreads names fromGET /applications/:id/variablesand changes keys withPATCHon it, neverGET /applications/:id, whose row carries the values. A secret goes in by a hidden question in a terminal or bycontext.stdinotherwise; read stdin only whenstdin.isTTYis false, and refuse (exit 2) a terminal that may not be asked rather than wait on it. x-organization-idis sent by every clientinOrganization(id)gives, whichlookUpTargetand the catalog use. The server refuses a non-member with 403NOT_ORGANIZATION_MEMBER(api-schemas);refusalFromResponsehints at--org,CLOUDGATE_ORGand the link for it.- Following a Deployment is
watchDeployment(src/deployment-watch.ts) withdeploymentLogFollower(src/deployment-log-stream.ts) oncheckInstance(...).endpoints.websocket, the client'ssocketHeaders()andcontext.openSocket. It ends whenGET /deployments/:id(deploymentSchemainapi-schemas) says done,error(printed "failed") or cancelled, never because the stream did:/listen-deploymentistail -fand does not close.logs --deployment -freuses both. - Ctrl-C goes to a command only when it listens (
context.interrupts.listen), asdeploydoes while it watches a Deployment that goes on without it; it then prints how to pick the watch up again and returns 130. With no listener, or on a second Ctrl-C,main.tsexits 130 at once. - Tests never wait on a clock:
context.sleepis a timer in the process and whatever the test passes in the unit lane, asopenSocketis Node'sWebSocketand a double there. - Docker is a boundary like the network. A command runs
dockeronly throughcontext.docker, which the unit lane replaces as it doesfetch; the realdockeris walked once, in the e2e suite.template tryremoves its stack in one place,TryRun.remove(src/commands/template-try.ts), so whatever ends a run reaches it: a pass, a fail,--timeoutor Ctrl-C. The last two stop the run through oneAbortSignal, which the Docker seam takes to end adocker compose upstill pulling; the deadline is read fromnowbetweensleeps, so a test's clock drives it.
