fargone-cli

The official command-line interface for Fargone — the collective PaaS. Deploy apps, attach databases, manage env vars and watch logs straight from your terminal, with zero runtime dependencies (Node ≥ 18).

Install

npm install -g fargone-cli

Sign in

fargone login

The CLI signs in through the platform's OAuth device flow: it opens your browser, you confirm with a passkey (Face ID, Touch ID, Windows Hello, a security key) or SSO, and the terminal receives a scoped access token. No tokens are stored on disk until you approve.

• Point at a self-hosted instance with fargone login --host https://paas.example.com (or FARGONE_HOST, or the --host flag on any command).
• No browser on the machine? fargone login --no-browser prints the URL + code.
• Scripting? FARGONE_TOKEN=<token> fargone apps --json.

Credentials live in ~/.config/fargone/config.json (0600), one account per host, refreshed automatically.

Usage

fargone <command> [args] [--host <url>] [--json]

| Area | Commands | | ---- | -------- | | Auth | login, logout, whoami, status, doctor | | Apps | apps, apps create <name>, apps info <slug>, apps deploy <slug> --watch | | | deploy <slug> <dir\|.zip> --watch, apps stop\|restart\|delete <slug> | | Logs | logs <slug> --follow [--build] | | Env | env <slug>, env set <slug> KEY=V …, env unset <slug> KEY | | DB | db <slug> add postgres\|redis\|mariadb\|mongo, db <slug> list | | Files| cdn, cdn upload <file>, cdn rm <id> | | | cdn env <slug>, cdn rotate <slug> | | Quota| quota, quota request apps 20 "for a side project" | | Misc | open [slug] |

--json prints machine-readable output for piping into jq.

CDN env for local development

Deployed apps get a managed CDN token injected as environment variables (FARGONE_CDN_URL, FARGONE_CDN_PUBLIC_URL, FARGONE_CDN_TOKEN, FARGONE_CDN_PREFIX). Mirror them locally so your app behaves identically:

fargone cdn env my-app        # prints the export block for your .env
fargone cdn rotate my-app     # invalidates the old token, prints the new one

Use as a library

The same package is the official Node.js API. Importing it never touches the CLI code paths.

import { FargoneClient, ApiError } from "fargone-cli";

const client = new FargoneClient({
  host: "https://fargone.sh",
  token: process.env.FARGONE_TOKEN, // OAuth access token (device flow or your own)
});

const me = await client.me();                    // account + quota + platform status
const apps = await client.listApps();
await client.createApp({ name: "my-app" });
const dep = await client.deployZip("my-app", new TextEncoder().encode(buf));
await client.waitForDeployment("my-app", dep.id);
await client.setEnv("my-app", "NODE_ENV", "production");
const cdnEnv = await client.cdnEnv("my-app");    // managed CDN vars for the app

FargoneClient.forHost(host) binds to the account stored by fargone login and persists refreshed tokens back to ~/.config/fargone. Types ship with the package (FargoneClient, Me, App, CdnEnvVars, ApiError, …).

Examples

fargone login
fargone apps
fargone apps create my-app --github https://github.com/you/repo
fargone deploy my-app ./project --watch
fargone env set my-app DATABASE_URL=postgres://… NODE_ENV=production
fargone logs my-app --follow
fargone db my-app add postgres
fargone quota request storage 10 "media uploads"

Development

The CLI lives in cli/ inside the fargone monorepo. Source is TypeScript; npm run build emits the compiled package to dist/.

npm run build                     # tsc -> dist/ (bin/fargone.mjs runs this)
node bin/fargone.mjs --help       # run from source
npm link                          # or link it globally

The platform side:

• API routes accept Authorization: Bearer <token> (OAuth access tokens).
• fg_cli is a well-known public OAuth client seeded on demand for the device flow (src/lib/cli-client.ts); no registration needed.