@newly/cli 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# newly CLI
+
+Develop, provision, and deploy your [Newly](https://newly.app) backend from the terminal.
+
+## Install
+
+```bash
+npm i -g @newly/cli
+```
+
+Installs the `newly` binary. Requires **Node ≥ 20**.
+
+## Quick start
+
+```bash
+newly login              # authenticate in the browser
+newly pull <project-id>  # download project code + link this directory
+# edit code…
+newly deploy             # deploy to dev
+newly deploy --env prod  # ship to prod
+```
+
+## Auth
+
+```bash
+newly login          # opens a browser, stores a session token in ~/.newly/credentials
+newly login --manual # paste the credential instead of using the browser callback
+newly logout         # delete stored credentials
+```
+
+The token expires. Re-run `newly login` when commands report you're logged out.
+
+## Project linking
+
+Most commands target the project linked to the current directory, so you don't pass `--project` every time.
+
+- `newly pull <project-id>` and `newly create` link automatically.
+- `newly link <project-id>` links a directory without downloading anything.
+- Pass `--project <id>` to any command to override the link.
+
+## Dev vs prod deploys
+
+| | Source | Notes |
+|---|---|---|
+| `newly deploy` (dev) | **your local code** | Fast inner loop. Ephemeral — overwritten the next time the project is built on the Newly platform. Not a rollback target. |
+| `newly deploy --env prod` | **project code at HEAD** | Runs server-side, ignores local edits. Push your changes into the project first. |
+
+Prod actions prompt for confirmation. Pass `--yes` to skip it in scripts.
+
+> Only **newly-backend-stack** projects (Python api-service + Node auth-service) are CLI-deployable. Run `newly stack` to check. Specular-stack projects must be deployed from the Newly web app.
+
+## Commands
+
+### `newly pull [project-id]`
+Download the project working tree (app + backend) into the current directory and link it.
+- `--branch <name>` — pull a specific branch (default: project's active branch).
+- `--force` — overwrite a non-empty directory (discards local changes).
+
+### `newly create [name]`
+Create a new backend-only project here, scaffold `backend/`, and link the directory. Provisions the dev backend by default.
+- `--no-provision` — create without provisioning.
+
+Run in a directory with no `backend/` and no existing link.
+
+### `newly link <project-id>`
+Link the current directory to a project without downloading code.
+
+### `newly status`
+Show dev and prod status, service URLs, deployed SHA, and last error.
+- `--project <id>`
+
+### `newly stack`
+Show which backend stack the project uses and whether it's CLI-deployable.
+- `--project <id>`
+
+### `newly up`
+Provision the backend (if not already) and deploy.
+- `--env <dev|prod>` (default `dev`)
+- `--region <region>` — region for dev provisioning (default `us-central1`)
+- `--project <id>`
+- `--yes` — skip the prod confirmation prompt
+
+### `newly deploy`
+Deploy the backend.
+- `--env <dev|prod>` (default `dev`)
+- `--project <id>`
+- `--yes` — skip the prod confirmation prompt
+
+### `newly logs`
+Tail backend service logs. **Dev only.**
+- `--service <api|auth>` (default `api`)
+- `-n, --lines <n>` (default `200`)
+- `--since <duration>` — relative window, e.g. `30s`, `5m`, `2h`
+- `--start <iso>` / `--end <iso>` — absolute window (ISO 8601)
+- `--project <id>`
+
+### `newly secrets list`
+List the secret keys set for a service (names only). **Dev only.**
+- `--service <api|auth>` (default `api`)
+- `--project <id>`
+
+### `newly secrets set <key> <value>`
+Set a backend secret. **Dev only.** Redeploy to apply.
+- `--service <api|auth>` (default `api`)
+- `--project <id>`
+
+### `newly db url`
+Print a readonly Postgres URL for the backend database. **Dev only.**
+- `--project <id>`
+
+## Files
+
+- `~/.newly/credentials` — session token (mode `600`). Override the directory with `NEWLY_HOME`.
+- `.newly/project.json` — per-directory project link.

package/dist/api.js

@@ -0,0 +1,113 @@
+export class ApiError extends Error {
+    status;
+    detail;
+    constructor(status, detail) {
+        super(`API ${status}: ${detail}`);
+        this.status = status;
+        this.detail = detail;
+    }
+}
+export class ApiClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+    }
+    async request(method, path, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            let detail = await res.text();
+            try {
+                detail = JSON.parse(detail).detail ?? detail;
+            }
+            catch {
+            }
+            throw new ApiError(res.status, detail);
+        }
+        const contentType = res.headers.get('content-type') ?? '';
+        return contentType.includes('application/json') ? res.json() : res;
+    }
+    get(path) {
+        return this.request('GET', path);
+    }
+    post(path, body) {
+        return this.request('POST', path, body);
+    }
+    async upload(path, body, contentType) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                'Content-Type': contentType,
+            },
+            body: body,
+        });
+        if (!res.ok) {
+            let detail = await res.text();
+            try {
+                detail = JSON.parse(detail).detail ?? detail;
+            }
+            catch {
+            }
+            throw new ApiError(res.status, detail);
+        }
+        const contentType_ = res.headers.get('content-type') ?? '';
+        return contentType_.includes('application/json') ? res.json() : res;
+    }
+    async getBinary(path) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${this.token}` },
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            throw new ApiError(res.status, detail || res.statusText);
+        }
+        return Buffer.from(await res.arrayBuffer());
+    }
+    async *stream(path) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${this.token}`, Accept: 'text/event-stream' },
+        });
+        if (!res.ok) {
+            let detail = await res.text().catch(() => '');
+            try {
+                detail = JSON.parse(detail).detail ?? detail;
+            }
+            catch {
+            }
+            throw new ApiError(res.status, detail || res.statusText);
+        }
+        const decoder = new TextDecoder();
+        for await (const chunk of res.body) {
+            yield decoder.decode(chunk, { stream: true });
+        }
+        const tail = decoder.decode();
+        if (tail)
+            yield tail;
+    }
+}
+export function friendlyApiError(err) {
+    if (!(err instanceof ApiError))
+        return String(err);
+    if (err.status === 401)
+        return 'Session expired or invalid — run `newly login`.';
+    if (err.status === 403)
+        return err.detail ? `Forbidden: ${err.detail}` : 'Forbidden.';
+    if (err.status === 404)
+        return `Not found: ${err.detail}`;
+    if (err.status === 409)
+        return err.detail;
+    if (err.status === 503)
+        return 'The platform is at capacity right now — please try again in a few minutes.';
+    return err.message;
+}

package/dist/archive.js

@@ -0,0 +1,113 @@
+import { mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { create as tarCreate, extract as tarExtract, list as tarList } from 'tar';
+import { Buffer } from 'node:buffer';
+export const SNAPSHOT_EXCLUDE = new Set([
+    '.git',
+    'node_modules',
+    '.venv',
+    '.expo',
+    '.next',
+    '.turbo',
+    '.vercel',
+    '.cache',
+    'dist',
+    'build',
+    'web-build',
+    '.natively',
+    'android',
+    'ios',
+    '.local',
+    '.npm',
+    '.pnpm-store',
+    '.yarn',
+    '.bun',
+    '__pycache__',
+    'agent_activity',
+    'branches',
+    'secrets',
+]);
+export const SNAPSHOT_EXCLUDE_FILE_GLOBS = [
+    '.env',
+    '.env.*',
+    '.env*.local',
+    '*.pem',
+    '*.key',
+    '*.p8',
+    '*.p12',
+    '*.jks',
+    '*.mobileprovision',
+    '.DS_Store',
+    '*.orig.*',
+    '*.tsbuildinfo',
+];
+const FILE_GLOB_REGEXPS = SNAPSHOT_EXCLUDE_FILE_GLOBS.map((glob) => new RegExp(`^${glob.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\\\*/g, '.*')}$`));
+function isExcluded(path) {
+    return path
+        .replace(/^\.\//, '')
+        .split('/')
+        .some((part) => SNAPSHOT_EXCLUDE.has(part));
+}
+function isExcludedFile(basename) {
+    return FILE_GLOB_REGEXPS.some((re) => re.test(basename));
+}
+function basenameOf(path) {
+    const parts = path.split('/');
+    return parts[parts.length - 1];
+}
+export async function createSnapshot(dir) {
+    const chunks = [];
+    const stream = tarCreate({
+        gzip: true,
+        cwd: dir,
+        filter: (p) => !isExcluded(p) && !isExcludedFile(basenameOf(p)),
+        portable: true,
+    }, ['.']);
+    for await (const chunk of stream) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+export async function extractSnapshot(data, dir) {
+    mkdirSync(dir, { recursive: true });
+    await new Promise((resolve, reject) => {
+        const stream = tarExtract({ cwd: dir });
+        stream.on('error', reject);
+        stream.on('finish', resolve);
+        stream.end(data);
+    });
+}
+export async function snapshotTopLevelEntries(data) {
+    const top = new Set();
+    for (const name of await listSnapshot(data)) {
+        const rel = name.replace(/^\.?\//, '');
+        const first = rel.split('/')[0];
+        if (first && first !== '.')
+            top.add(first);
+    }
+    return top;
+}
+export function pruneStaleTopLevel(dir, keep) {
+    const removed = [];
+    for (const entry of readdirSync(dir)) {
+        if (entry === '.newly')
+            continue;
+        if (keep.has(entry))
+            continue;
+        if (isExcluded(entry) || isExcludedFile(entry))
+            continue;
+        rmSync(join(dir, entry), { recursive: true, force: true });
+        removed.push(entry);
+    }
+    return removed;
+}
+export async function listSnapshot(data) {
+    const names = [];
+    await new Promise((resolve, reject) => {
+        const stream = tarList({ onentry: (e) => names.push(e.path) });
+        stream.on('error', reject);
+        stream.on('finish', resolve);
+        stream.end(data);
+    });
+    return names;
+}

package/dist/commands/create.js

@@ -0,0 +1,60 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ApiClient, ApiError, friendlyApiError } from '../api.js';
+import { requireCredentials, writeProjectLink } from '../config.js';
+import { extractSnapshot } from '../archive.js';
+export async function runCreate(client, dir, opts) {
+    if (existsSync(join(dir, 'backend'))) {
+        throw new Error('A `backend/` directory already exists here. Run `newly create` in a directory without one.');
+    }
+    const { project_id, status } = await client.post('/newly_backend/create_project', {
+        name: opts.name,
+        provision: opts.provision ?? true,
+    });
+    writeProjectLink(dir, {
+        projectId: project_id,
+        pulledSha: null,
+        pulledAt: new Date().toISOString(),
+    });
+    try {
+        const tar = await client.getBinary('/newly_backend/backend_template');
+        await extractSnapshot(tar, dir);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`Project ${project_id} was created and linked, but scaffolding the backend template failed: ${msg}. The project exists server-side.`);
+    }
+    if (status === 'provisioning') {
+        console.log(`Created backend project ${project_id} and scaffolded backend/ here. ` +
+            `Provisioning the dev backend… check with \`newly status\`. Edit, then \`newly deploy\`.`);
+    }
+    else {
+        console.log(`Created backend project ${project_id} and scaffolded backend/ here ` +
+            `(not provisioned — run \`newly up\` when ready). Edit, then \`newly deploy\`.`);
+    }
+    return project_id;
+}
+export function registerCreate(program) {
+    program
+        .command('create')
+        .description('Create a new backend-only Newly project here (scaffold + provision)')
+        .argument('[name]', 'project name (generated if omitted)')
+        .option('--no-provision', 'create without provisioning the backend')
+        .action(async (name, opts) => {
+        try {
+            if (existsSync(join(process.cwd(), '.newly', 'project.json'))) {
+                throw new Error('This directory is already linked to a project. Use a fresh directory for `newly create`.');
+            }
+            const creds = requireCredentials();
+            const client = new ApiClient(creds.apiUrl, creds.token);
+            await runCreate(client, process.cwd(), {
+                name,
+                provision: opts.provision,
+            });
+        }
+        catch (e) {
+            console.error(e instanceof ApiError ? friendlyApiError(e) : String(e instanceof Error ? e.message : e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/deploy.js

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ApiClient, ApiError, friendlyApiError } from '../api.js';
+import { requireCredentials, resolveProject } from '../config.js';
+import { createSnapshot } from '../archive.js';
+import { parseSseFrames } from '../sse.js';
+const POLL_INTERVAL_MS = 5_000;
+const POLL_TIMEOUT_MS = 20 * 60 * 1000;
+export async function pollRun(client, runId, opts = {}) {
+    const intervalMs = opts.intervalMs ?? POLL_INTERVAL_MS;
+    const timeoutMs = opts.timeoutMs ?? POLL_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const run = await client.get(`/newly_backend/deploy_runs/${runId}`);
+        if (run.status !== 'running')
+            return run;
+        if (Date.now() > deadline)
+            throw new Error(`Deploy run ${runId} timed out after ${timeoutMs / 1000}s`);
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
+export async function streamRun(client, runId, print = (s) => process.stdout.write(s)) {
+    let buffer = '';
+    let started = false;
+    try {
+        for await (const chunk of client.stream(`/newly_backend/deploy_runs/${runId}/logs/stream`)) {
+            started = true;
+            buffer = (buffer + chunk).replace(/\r\n/g, '\n');
+            const lastSep = buffer.lastIndexOf('\n\n');
+            if (lastSep === -1)
+                continue;
+            const ready = buffer.slice(0, lastSep + 2);
+            buffer = buffer.slice(lastSep + 2);
+            for (const frame of parseSseFrames(ready)) {
+                if (frame.event === 'done') {
+                    return JSON.parse(frame.data);
+                }
+                try {
+                    print(JSON.parse(frame.data));
+                }
+                catch {
+                    print(frame.data);
+                }
+            }
+        }
+    }
+    catch (e) {
+        if (e instanceof ApiError && e.status === 404) {
+            return pollRun(client, runId);
+        }
+        if (started) {
+            return pollRun(client, runId);
+        }
+        throw e;
+    }
+    return pollRun(client, runId);
+}
+export function finishOrThrow(run, label) {
+    if (run.status === 'succeeded') {
+        console.log(`${label} deploy succeeded.`);
+        return;
+    }
+    if (run.failure_reason === 'no_backend_code') {
+        throw new Error('No backend code to deploy (backend/api-service missing).');
+    }
+    throw new Error(`${label} deploy failed (${run.failure_reason ?? 'unknown'}):\n${run.output_tail ?? ''}`);
+}
+export async function runDevDeploy(projectId, client, dir) {
+    if (!existsSync(join(dir, 'backend', 'api-service'))) {
+        throw new Error('No backend/api-service in this directory. Run `newly pull <project-id>` first, ' +
+            'or cd into a pulled project.');
+    }
+    console.log('Packaging local backend…');
+    const snapshot = await createSnapshot(dir);
+    const kib = snapshot.length < 1024 ? '<1' : Math.round(snapshot.length / 1024).toString();
+    console.log(`Uploading snapshot (${kib} KiB) and deploying server-side…`);
+    const { run_id } = await client.upload(`/newly_backend/deploy/${projectId}?env=dev`, snapshot, 'application/gzip');
+    const run = await streamRun(client, run_id);
+    finishOrThrow(run, 'dev');
+}
+export async function runProdDeploy(projectId, client) {
+    console.log('Deploying prod from the canonical project code (repo HEAD)…');
+    const { run_id } = await client.post(`/newly_backend/deploy/${projectId}`, { env: 'prod' });
+    const run = await streamRun(client, run_id);
+    finishOrThrow(run, 'prod');
+}
+export function registerDeploy(program) {
+    program
+        .command('deploy')
+        .description('Deploy the backend server-side from your local code (dev only; prod ships via Promote in the web app)')
+        .option('--env <env>', 'dev (prod is not supported via the CLI yet)', 'dev')
+        .option('--project <id>', 'project id (defaults to the linked directory)')
+        .option('--yes', 'skip the prod confirmation prompt', false)
+        .action(async (opts) => {
+        try {
+            if (opts.env !== 'dev' && opts.env !== 'prod')
+                throw new Error('--env must be dev or prod');
+            if (opts.env === 'prod') {
+                throw new Error('Prod deploys are not supported via the CLI yet — use Promote in the Newly web app.');
+            }
+            const creds = requireCredentials();
+            const projectId = resolveProject(process.cwd(), opts.project);
+            const client = new ApiClient(creds.apiUrl, creds.token);
+            const stackInfo = await client.get(`/newly_backend/stack/${projectId}`);
+            if (!stackInfo.cli_deployable) {
+                throw new Error('This project is on the Specular stack (a single Node/drizzle backend), which `newly deploy` does not support. ' +
+                    'Only newly-backend-stack projects (Python api-service + Node auth-service) are CLI-deployable.');
+            }
+            await runDevDeploy(projectId, client, process.cwd());
+        }
+        catch (e) {
+            console.error(e instanceof ApiError ? friendlyApiError(e) : String(e instanceof Error ? e.message : e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/link.js

@@ -0,0 +1,17 @@
+import { readProjectLink, writeProjectLink } from '../config.js';
+export function registerLink(program) {
+    program
+        .command('link')
+        .argument('<project-id>', 'Newly project id')
+        .description('Associate the current directory with a project (no download) so deploy/status/logs work here')
+        .action((projectId) => {
+        const dir = process.cwd();
+        const existing = readProjectLink(dir);
+        writeProjectLink(dir, {
+            projectId,
+            pulledSha: existing?.projectId === projectId ? existing.pulledSha : null,
+            pulledAt: new Date().toISOString(),
+        });
+        console.log(`Linked ${dir} to project ${projectId}. You can now run \`newly deploy\`, \`newly status\`, etc. here.`);
+    });
+}

package/dist/commands/login.js

@@ -0,0 +1,149 @@
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { clearCredentials, saveCredentials } from '../config.js';
+const DEFAULT_APP_URL = 'https://newly.app';
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+export async function startCallbackServer(state, appOrigin, timeoutMs) {
+    let resolvePayload;
+    let rejectPayload;
+    const payloadPromise = new Promise((resolve, reject) => {
+        resolvePayload = resolve;
+        rejectPayload = reject;
+    });
+    const timer = setTimeout(() => rejectPayload(new Error(`Login timed out after ${timeoutMs / 1000}s`)), timeoutMs);
+    const corsHeaders = {
+        'Access-Control-Allow-Origin': appOrigin,
+        'Access-Control-Allow-Methods': 'POST, OPTIONS',
+        'Access-Control-Allow-Headers': 'content-type',
+    };
+    const server = http.createServer((req, res) => {
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204, corsHeaders);
+            res.end();
+            return;
+        }
+        if (req.method !== 'POST') {
+            res.writeHead(405, corsHeaders);
+            res.end();
+            return;
+        }
+        let body = '';
+        req.on('data', (chunk) => (body += chunk));
+        req.on('end', () => {
+            try {
+                const parsed = JSON.parse(body);
+                if (parsed.state !== state) {
+                    res.writeHead(403, corsHeaders);
+                    res.end('state mismatch');
+                    return;
+                }
+                res.writeHead(200, { ...corsHeaders, 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ ok: true }));
+                clearTimeout(timer);
+                resolvePayload(parsed);
+            }
+            catch {
+                res.writeHead(400, corsHeaders);
+                res.end('bad request');
+            }
+        });
+    });
+    const port = await new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            resolve(typeof addr === 'object' && addr ? addr.port : 0);
+        });
+    });
+    return {
+        port,
+        waitForToken: () => payloadPromise,
+        close: () => {
+            clearTimeout(timer);
+            server.close();
+        },
+    };
+}
+function openBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {
+    });
+    child.unref();
+}
+export function parseManualCredential(blob) {
+    let parsed;
+    try {
+        parsed = JSON.parse(blob);
+    }
+    catch {
+        throw new Error('Could not parse the pasted credential as JSON. Copy the entire blob shown in the browser and try again.');
+    }
+    const c = parsed;
+    if (typeof c.token !== 'string' || typeof c.expiresIn !== 'number' || typeof c.apiUrl !== 'string') {
+        throw new Error('Pasted credential is missing required fields (expected JSON with token, expiresIn, apiUrl). ' +
+            'Copy the entire blob shown in the browser.');
+    }
+    return { token: c.token, expiresIn: c.expiresIn, apiUrl: c.apiUrl };
+}
+export function registerLogin(program) {
+    program
+        .command('login')
+        .description('Log in with your Newly account via the browser')
+        .option('--app-url <url>', 'Newly web app URL', DEFAULT_APP_URL)
+        .option('--manual', 'paste the credential from the browser instead of using the local callback', false)
+        .action(async (opts) => {
+        try {
+            if (opts.manual) {
+                const { createInterface } = await import('node:readline/promises');
+                const rl = createInterface({ input: process.stdin, output: process.stdout });
+                const blob = await rl.question('Paste the credential from the browser: ');
+                rl.close();
+                const parsed = parseManualCredential(blob);
+                saveCredentials({
+                    token: parsed.token,
+                    apiUrl: parsed.apiUrl,
+                    appUrl: opts.appUrl,
+                    expiresAt: Math.floor(Date.now() / 1000) + parsed.expiresIn,
+                });
+                console.log('Logged in.');
+                return;
+            }
+            const state = crypto.randomBytes(16).toString('hex');
+            const appOrigin = new URL(opts.appUrl).origin;
+            const { port, waitForToken, close } = await startCallbackServer(state, appOrigin, LOGIN_TIMEOUT_MS);
+            const loginUrl = `${opts.appUrl}/cli-auth?port=${port}&state=${state}`;
+            console.log(`Opening your browser to authorize the CLI…\n  ${loginUrl}\n`);
+            console.log("If the browser doesn't open, paste the URL above into it manually.");
+            openBrowser(loginUrl);
+            try {
+                const payload = await waitForToken();
+                saveCredentials({
+                    token: payload.token,
+                    apiUrl: payload.apiUrl,
+                    appUrl: opts.appUrl,
+                    expiresAt: Math.floor(Date.now() / 1000) + payload.expiresIn,
+                });
+                console.log('Logged in. Credentials saved to ~/.newly/credentials');
+            }
+            finally {
+                close();
+            }
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : String(e));
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command('logout')
+        .description('Delete the stored CLI credential')
+        .action(() => {
+        clearCredentials();
+        console.log('Logged out.');
+    });
+}

package/dist/commands/misc.js

@@ -0,0 +1,148 @@
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials, resolveProject } from '../config.js';
+export function assertDevOnly(env, command) {
+    if (env !== 'dev') {
+        throw new Error(`\`newly ${command}\` is dev-only from the CLI. Prod ${command} requires the Newly web app (a browser session).`);
+    }
+}
+export function parseDuration(s) {
+    const m = /^(\d+)(s|m|h)$/.exec(s.trim());
+    if (!m)
+        throw new Error(`Invalid duration "${s}" (use e.g. 30s, 5m, 2h)`);
+    const n = Number(m[1]);
+    const unit = m[2];
+    const mult = unit === 's' ? 1_000 : unit === 'm' ? 60_000 : 3_600_000;
+    return n * mult;
+}
+const ISO_8601 = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})?)?$/;
+function validateIso(s) {
+    if (!ISO_8601.test(s) || Number.isNaN(Date.parse(s))) {
+        throw new Error(`Invalid ISO 8601 timestamp "${s}" (expected e.g. 2026-06-15 or 2026-06-15T08:00:00Z)`);
+    }
+}
+export function resolveLogWindow(opts, now = Date.now()) {
+    let start = opts.start;
+    if (!start && opts.since)
+        start = new Date(now - parseDuration(opts.since)).toISOString();
+    if (opts.start)
+        validateIso(opts.start);
+    if (opts.end)
+        validateIso(opts.end);
+    return { start, end: opts.end };
+}
+export async function fetchLogs(client, projectId, env, service, n, bounds = {}) {
+    const body = { project_id: projectId, env, service, n };
+    if (bounds.start)
+        body.start = bounds.start;
+    if (bounds.end)
+        body.end = bounds.end;
+    const out = await client.post('/newly_backend/tail_logs', body);
+    if (typeof out.logs === 'string')
+        return out.logs;
+    if (Array.isArray(out.lines))
+        return out.lines.join('\n');
+    return JSON.stringify(out, null, 2);
+}
+export async function listSecrets(client, projectId, env, service) {
+    const out = await client.get(`/newly_backend/read_secrets?project_id=${encodeURIComponent(projectId)}&env=${env}&service=${service}`);
+    if (Array.isArray(out.keys))
+        return [...out.keys].sort().join('\n');
+    const secrets = out.secrets ?? out;
+    return Object.keys(secrets).sort().join('\n');
+}
+export async function setSecret(client, projectId, env, service, key, value) {
+    await client.post('/newly_backend/set_secret', {
+        project_id: projectId,
+        env,
+        service,
+        key,
+        value,
+    });
+}
+export async function getDbUrl(client, projectId, env) {
+    const out = await client.get(`/newly_backend/readonly_db_url?project_id=${encodeURIComponent(projectId)}&env=${env}`);
+    return out.database_url ?? out.url ?? JSON.stringify(out);
+}
+function makeClient(project) {
+    const creds = requireCredentials();
+    return {
+        client: new ApiClient(creds.apiUrl, creds.token),
+        projectId: resolveProject(process.cwd(), project),
+    };
+}
+export function registerMisc(program) {
+    program
+        .command('logs')
+        .description('Tail backend service logs')
+        .option('--env <env>', 'dev or prod', 'dev')
+        .option('--service <service>', 'api or auth', 'api')
+        .option('-n, --lines <n>', 'number of lines', '200')
+        .option('--since <duration>', 'relative window, e.g. 5m, 1h, 30s')
+        .option('--start <iso>', 'window start (ISO 8601 timestamp)')
+        .option('--end <iso>', 'window end (ISO 8601 timestamp)')
+        .option('--project <id>', 'project id')
+        .action(async (opts) => {
+        try {
+            assertDevOnly(opts.env, 'logs');
+            const bounds = resolveLogWindow(opts);
+            const { client, projectId } = makeClient(opts.project);
+            console.log(await fetchLogs(client, projectId, opts.env, opts.service, Number(opts.lines), bounds));
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+    const secrets = program.command('secrets').description('Manage backend secrets');
+    secrets
+        .command('list')
+        .option('--env <env>', 'dev or prod', 'dev')
+        .option('--service <service>', 'api or auth', 'api')
+        .option('--project <id>', 'project id')
+        .action(async (opts) => {
+        try {
+            assertDevOnly(opts.env, 'secrets list');
+            const { client, projectId } = makeClient(opts.project);
+            console.log(await listSecrets(client, projectId, opts.env, opts.service));
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+    secrets
+        .command('set')
+        .argument('<key>')
+        .argument('<value>')
+        .option('--env <env>', 'dev or prod', 'dev')
+        .option('--service <service>', 'api or auth', 'api')
+        .option('--project <id>', 'project id')
+        .action(async (key, value, opts) => {
+        try {
+            assertDevOnly(opts.env, 'secrets set');
+            const { client, projectId } = makeClient(opts.project);
+            await setSecret(client, projectId, opts.env, opts.service, key, value);
+            console.log(`Secret ${key} set for ${opts.service} (${opts.env}). Redeploy to apply.`);
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+    const db = program.command('db').description('Database helpers');
+    db.command('url')
+        .description('Print a readonly Postgres URL for the backend database')
+        .option('--env <env>', 'dev or prod', 'dev')
+        .option('--project <id>', 'project id')
+        .action(async (opts) => {
+        try {
+            assertDevOnly(opts.env, 'db url');
+            const { client, projectId } = makeClient(opts.project);
+            console.log(await getDbUrl(client, projectId, opts.env));
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/pull.js

@@ -0,0 +1,53 @@
+import { readdirSync } from 'node:fs';
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials, resolveProject, writeProjectLink } from '../config.js';
+import { extractSnapshot, pruneStaleTopLevel, snapshotTopLevelEntries } from '../archive.js';
+export function assertPullTarget(dir, force) {
+    const entries = readdirSync(dir).filter((e) => e !== '.newly');
+    if (entries.length > 0 && !force) {
+        throw new Error(`Target directory is not empty. Re-run with --force to overwrite local files (this discards local changes).`);
+    }
+}
+export async function extractTarball(data, dir) {
+    await extractSnapshot(data, dir);
+}
+export function registerPull(program) {
+    program
+        .command('pull')
+        .argument('[project-id]', 'Newly project id (defaults to the linked project in this directory)')
+        .description('Download the project working tree (app + backend) into the current directory')
+        .option('--force', 'overwrite files in a non-empty directory', false)
+        .option('--branch <name>', 'branch to pull (defaults to the project active branch / main)')
+        .action(async (projectIdArg, opts) => {
+        try {
+            const creds = requireCredentials();
+            const dir = process.cwd();
+            const projectId = resolveProject(dir, projectIdArg);
+            assertPullTarget(dir, opts.force);
+            const client = new ApiClient(creds.apiUrl, creds.token);
+            const query = opts.branch ? `?branch=${encodeURIComponent(opts.branch)}` : '';
+            console.log(`Downloading project ${projectId}${opts.branch ? ` (branch ${opts.branch})` : ''}…`);
+            const res = (await client.get(`/newly_backend/repo_archive/${projectId}${query}`));
+            const data = Buffer.from(await res.arrayBuffer());
+            if (opts.force) {
+                const keep = await snapshotTopLevelEntries(data);
+                const removed = pruneStaleTopLevel(dir, keep);
+                if (removed.length > 0) {
+                    console.log(`Removed ${removed.length} stale top-level ${removed.length === 1 ? 'entry' : 'entries'} not in the pulled tree: ${removed.join(', ')}`);
+                }
+            }
+            await extractTarball(data, dir);
+            const pulledBranch = res.headers.get('x-newly-branch');
+            writeProjectLink(dir, {
+                projectId,
+                pulledSha: res.headers.get('x-newly-head-sha'),
+                pulledAt: new Date().toISOString(),
+            });
+            console.log(`Pulled${pulledBranch ? ` branch ${pulledBranch}` : ''} into ${dir} and linked to project ${projectId}.`);
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/stack.js

@@ -0,0 +1,29 @@
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials, resolveProject } from '../config.js';
+export function registerStack(program) {
+    program
+        .command('stack')
+        .description('Show which backend stack a project uses (newly-backend or specular)')
+        .option('--project <id>', 'project id (defaults to the linked directory)')
+        .action(async (opts) => {
+        try {
+            const creds = requireCredentials();
+            const projectId = resolveProject(process.cwd(), opts.project);
+            const client = new ApiClient(creds.apiUrl, creds.token);
+            const out = await client.get(`/newly_backend/stack/${projectId}`);
+            const stack = out.stack ?? 'unknown';
+            console.log(`stack: ${stack}`);
+            if (out.cli_deployable) {
+                console.log('✓ CLI-deployable — Python api-service + Node auth-service');
+            }
+            else {
+                console.log('✗ not CLI-deployable — this project is on the Specular stack ' +
+                    '(a single Node/drizzle backend). `newly deploy` supports only the newly-backend stack.');
+            }
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/status.js

@@ -0,0 +1,110 @@
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials, resolveProject } from '../config.js';
+function elapsed(since) {
+    if (!since)
+        return '';
+    const ms = Date.now() - new Date(since).getTime();
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m ${s % 60}s`;
+    return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
+}
+function renderProvisioningStages(s) {
+    const done = '  [✓]';
+    const current = '  [→]';
+    const todo = '  [ ]';
+    const stages = [
+        {
+            label: 'Project created',
+            note: 'backend entry registered in Newly',
+            complete: true,
+        },
+        {
+            label: 'Cloud environment assigned',
+            note: 'dedicated cloud environment allocated for your backend',
+            complete: s.cloud_env_assigned,
+        },
+        {
+            label: 'Infrastructure provisioned',
+            note: 'container registry, storage buckets, IAM roles set up',
+            complete: s.neon_ready,
+        },
+        {
+            label: 'Database created',
+            note: 'Postgres database ready for your API service',
+            complete: s.neon_ready,
+        },
+        {
+            label: 'Environment secrets wired',
+            note: 'DB credentials, API keys and auth tokens encrypted and stored',
+            complete: s.secrets_wired,
+        },
+        {
+            label: "Run 'newly deploy'",
+            note: 'builds and deploys your backend code for the first time',
+            complete: false,
+        },
+    ];
+    let foundCurrent = false;
+    const lines = [];
+    for (const stage of stages) {
+        const note = `  — ${stage.note}`;
+        if (stage.complete) {
+            lines.push(`${done} ${stage.label}${note}`);
+        }
+        else if (!foundCurrent) {
+            foundCurrent = true;
+            lines.push(`${current} ${stage.label}${note}`);
+        }
+        else {
+            lines.push(`${todo} ${stage.label}${note}`);
+        }
+    }
+    return lines;
+}
+export function renderStatus(body) {
+    const lines = [];
+    for (const env of ['dev', 'prod']) {
+        const s = body[env];
+        if (!s) {
+            lines.push(`${env}: not provisioned`);
+            continue;
+        }
+        if (s.status === 'provisioning') {
+            const age = elapsed(s.created_at);
+            lines.push(`${env}: provisioning${age ? ` (${age})` : ''}`);
+            lines.push(...renderProvisioningStages(s));
+        }
+        else {
+            lines.push(`${env}: ${s.status}`);
+            lines.push(`  auth: ${s.auth_hostname}`);
+            lines.push(`  api:  ${s.api_hostname}`);
+            if (s.current_git_sha)
+                lines.push(`  deployed sha: ${s.current_git_sha}`);
+        }
+        if (s.last_error)
+            lines.push(`  last error: ${s.last_error}`);
+    }
+    return lines.join('\n');
+}
+export function registerStatus(program) {
+    program
+        .command('status')
+        .description('Show backend status and service URLs')
+        .option('--project <id>', 'project id (defaults to the linked directory)')
+        .action(async (opts) => {
+        try {
+            const creds = requireCredentials();
+            const projectId = resolveProject(process.cwd(), opts.project);
+            const client = new ApiClient(creds.apiUrl, creds.token);
+            const body = await client.get(`/newly_backend/status/${projectId}`);
+            console.log(renderStatus(body));
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/up.js

@@ -0,0 +1,85 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ApiClient, ApiError, friendlyApiError } from '../api.js';
+import { requireCredentials, resolveProject } from '../config.js';
+import { runDevDeploy, runProdDeploy } from './deploy.js';
+function defaultHasLocalBackend(dir) {
+    return existsSync(join(dir, 'backend', 'scripts', 'deploy.sh'));
+}
+export async function runUp(deps) {
+    const { client, projectId, env, region, cwd, print, hasLocalBackend = defaultHasLocalBackend, deployDev = runDevDeploy, deployProd = runProdDeploy, } = deps;
+    const stackInfo = await client.get(`/newly_backend/stack/${projectId}`);
+    if (!stackInfo.cli_deployable) {
+        throw new Error('This project is on the Specular stack (a single Node/drizzle backend), which `newly up` does not support. ' +
+            'Only newly-backend-stack projects (Python api-service + Node auth-service) are CLI-deployable.');
+    }
+    const status = await client.get(`/newly_backend/status/${projectId}`);
+    if (status[env]) {
+        print(`${env} backend already provisioned (status: ${status[env].status}).`);
+    }
+    else {
+        print(`Provisioning ${env} backend…`);
+        if (env === 'dev') {
+            await client.post(`/newly_backend/provision_dev/${projectId}`, {
+                dev_region: region,
+            });
+            print('Provisioned dev backend.');
+        }
+        else {
+            await client.post(`/newly_backend/provision_prod/${projectId}`);
+            print('Provisioned prod backend.');
+        }
+    }
+    if (env === 'dev') {
+        if (!hasLocalBackend(cwd)) {
+            print('Provisioned. No backend code in this directory — nothing to deploy yet.\n' +
+                'Run `newly pull ' + projectId + '` to get the project code, or develop on the ' +
+                'platform; the backend goes active on its first deploy.');
+            return;
+        }
+        await deployDev(projectId, client, cwd);
+    }
+    else {
+        await deployProd(projectId, client);
+    }
+    const finalStatus = await client.get(`/newly_backend/status/${projectId}`);
+    const s = finalStatus[env];
+    if (s) {
+        print(`\n${env} backend: ${s.status}`);
+        print(`  auth: ${s.auth_hostname}`);
+        print(`  api:  ${s.api_hostname}`);
+    }
+}
+export function registerUp(program) {
+    program
+        .command('up')
+        .description('Provision (if needed) and deploy the backend (dev only; prod ships via Promote in the web app)')
+        .option('--env <env>', 'dev (prod is not supported via the CLI yet)', 'dev')
+        .option('--region <region>', 'region for dev provisioning', 'us-central1')
+        .option('--project <id>', 'project id (defaults to the linked directory)')
+        .option('--yes', 'skip the prod confirmation prompt', false)
+        .action(async (opts) => {
+        try {
+            if (opts.env !== 'dev' && opts.env !== 'prod')
+                throw new Error('--env must be dev or prod');
+            if (opts.env === 'prod') {
+                throw new Error('Prod provisioning/deploys are not supported via the CLI yet — use Promote in the Newly web app.');
+            }
+            const creds = requireCredentials();
+            const projectId = resolveProject(process.cwd(), opts.project);
+            const client = new ApiClient(creds.apiUrl, creds.token);
+            await runUp({
+                client,
+                projectId,
+                env: opts.env,
+                region: opts.region,
+                cwd: process.cwd(),
+                print: console.log,
+            });
+        }
+        catch (e) {
+            console.error(e instanceof ApiError ? friendlyApiError(e) : String(e instanceof Error ? e.message : e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/config.js

@@ -0,0 +1,69 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+function newlyHome() {
+    return process.env.NEWLY_HOME ?? join(homedir(), '.newly');
+}
+function credentialsPath() {
+    return join(newlyHome(), 'credentials');
+}
+export function normalizeApiUrl(url) {
+    const trimmed = url.replace(/\/+$/, '');
+    return trimmed.endsWith('/api') ? trimmed : `${trimmed}/api`;
+}
+export function saveCredentials(creds) {
+    mkdirSync(newlyHome(), { recursive: true, mode: 0o700 });
+    const normalized = { ...creds, apiUrl: normalizeApiUrl(creds.apiUrl) };
+    writeFileSync(credentialsPath(), JSON.stringify(normalized, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(credentialsPath(), 0o600);
+}
+export function loadCredentials() {
+    if (!existsSync(credentialsPath()))
+        return null;
+    try {
+        const creds = JSON.parse(readFileSync(credentialsPath(), 'utf8'));
+        if (!creds.token || creds.expiresAt < Date.now() / 1000)
+            return null;
+        return { ...creds, apiUrl: normalizeApiUrl(creds.apiUrl) };
+    }
+    catch {
+        return null;
+    }
+}
+export function clearCredentials() {
+    rmSync(credentialsPath(), { force: true });
+}
+export function requireCredentials() {
+    const creds = loadCredentials();
+    if (!creds) {
+        throw new Error('Not logged in (or session expired). Run: newly login');
+    }
+    return creds;
+}
+export function writeProjectLink(dir, link) {
+    const linkDir = join(dir, '.newly');
+    mkdirSync(linkDir, { recursive: true });
+    const gitignorePath = join(linkDir, '.gitignore');
+    if (!existsSync(gitignorePath))
+        writeFileSync(gitignorePath, '*\n');
+    writeFileSync(join(linkDir, 'project.json'), JSON.stringify(link, null, 2) + '\n');
+}
+export function readProjectLink(dir) {
+    const path = join(dir, '.newly', 'project.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveProject(dir, explicit) {
+    if (explicit)
+        return explicit;
+    const link = readProjectLink(dir);
+    if (link?.projectId)
+        return link.projectId;
+    throw new Error('No project linked to this directory. Run `newly pull <project-id>` first, or pass --project <id>.');
+}

package/dist/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { registerLogin } from './commands/login.js';
+import { registerStatus } from './commands/status.js';
+import { registerLink } from './commands/link.js';
+import { registerCreate } from './commands/create.js';
+import { registerPull } from './commands/pull.js';
+import { registerDeploy } from './commands/deploy.js';
+import { registerUp } from './commands/up.js';
+import { registerMisc } from './commands/misc.js';
+import { registerStack } from './commands/stack.js';
+const program = new Command('newly')
+    .description('Develop, provision, and deploy Newly backends')
+    .version('0.1.0');
+registerLogin(program);
+registerStatus(program);
+registerLink(program);
+registerCreate(program);
+registerPull(program);
+registerDeploy(program);
+registerUp(program);
+registerMisc(program);
+registerStack(program);
+await program.parseAsync(process.argv);

package/dist/sse.js

@@ -0,0 +1,19 @@
+export function parseSseFrames(raw) {
+    const frames = [];
+    const blocks = raw.replace(/\r\n/g, '\n').split('\n\n');
+    blocks.pop();
+    for (const block of blocks) {
+        if (!block.trim())
+            continue;
+        let event = 'message';
+        const dataLines = [];
+        for (const line of block.split('\n')) {
+            if (line.startsWith('event:'))
+                event = line.slice(6).trim();
+            else if (line.startsWith('data:'))
+                dataLines.push(line.slice(5).replace(/^ /, ''));
+        }
+        frames.push({ event, data: dataLines.join('\n') });
+    }
+    return frames;
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@newly/cli",
+  "version": "0.1.0",
+  "description": "Develop, provision, and deploy Newly backends from your terminal",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": { "newly": "dist/index.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm lint && pnpm test && pnpm build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "tar": "^7.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^20.0.0",
+    "eslint": "^9.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.0.0"
+  }
+}