@apso/cli 0.46.4 → 0.47.1

package/dist/commands/deploy.d.ts

@@ -3,6 +3,7 @@ export default class Deploy extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        env: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         "no-wait": import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         "skip-migrate": import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;

package/dist/commands/deploy.js

@@ -5,6 +5,7 @@ const core_1 = require("@oclif/core");
 const base_command_1 = tslib_1.__importDefault(require("../lib/base-command"));
 const config_1 = require("../lib/config");
 const services_1 = require("../lib/api/services");
+const environments_1 = require("../lib/environments");
 const upgrade_1 = require("../lib/upgrade");
 const git = tslib_1.__importStar(require("../lib/git"));
 const apsorc_parser_1 = require("../lib/apsorc-parser");
@@ -15,6 +16,7 @@ const server_push_1 = require("../lib/deploy/server-push");
 class Deploy extends base_command_1.default {
     async run() {
         const { flags } = await this.parse(Deploy);
+        const env = (0, environments_1.asEnv)(flags.env);
         // Auth guard
         if (!config_1.credentials.isValid()) {
             this.error("Not logged in. Run 'apso login' first.");
@@ -73,10 +75,10 @@ class Deploy extends base_command_1.default {
         }
         // Determine source
         if (service.githubRepo || flags.repo) {
-            this.log(`Deploying "${service.name}" from ${service.githubRepo || flags.repo}#${flags.branch}...`);
+            this.log(`Deploying "${service.name}" (${env}) from ${service.githubRepo || flags.repo}#${flags.branch}...`);
         }
         else {
-            this.log(`Deploying "${service.name}" via Apso Platform...`);
+            this.log(`Deploying "${service.name}" (${env}) via Apso Platform...`);
         }
         // Confirmation
         if (!flags.yes && migrationCount > 0) {
@@ -98,24 +100,27 @@ class Deploy extends base_command_1.default {
             }
         }
         // Trigger build
-        const build = await (0, upgrade_1.withUpgradeRetry)(() => services_1.buildApi.trigger(link.workspaceSlug, link.serviceSlug));
+        const build = await (0, upgrade_1.withUpgradeRetry)(() => services_1.buildApi.trigger(link.workspaceSlug, link.serviceSlug, env), { workspaceSlug: link.workspaceSlug, serviceId: service.id });
         this.log(`Build started: ${build.id}`);
         if (flags["no-wait"]) {
-            this.log("Deploy triggered. Run 'apso status' to check progress.");
+            this.log(`Deploy triggered. Run 'apso status --env ${env}' to check progress.`);
             return;
         }
         // Poll with spinner
         const spinner = await (0, spinner_1.createSpinner)("Deploying...");
         spinner.start();
         const finalStatus = await services_1.buildApi.waitForCompletion(build.id, {
+            env,
             onProgress: (status) => {
                 spinner.text = `Deploy status: ${status.status}...`;
             },
         });
         if (finalStatus.status === "success") {
             spinner.succeed("Deploy succeeded.");
-            if (service.endpoint) {
-                this.log(`Endpoint: ${service.endpoint}`);
+            const row = env === "production" ? undefined : await services_1.envApi.get(service.id, env);
+            const endpoint = row ? row.url : service.endpoint;
+            if (endpoint) {
+                this.log(`Endpoint: ${endpoint}`);
             }
         }
         else {
@@ -271,8 +276,10 @@ Deploy.examples = [
     `$ apso deploy --yes`,
     `$ apso deploy --skip-migrate`,
     `$ apso deploy --no-wait`,
+    `$ apso deploy --env staging`,
 ];
 Deploy.flags = {
+    env: environments_1.envFlag,
     "no-wait": core_1.Flags.boolean({
         description: "Trigger deploy without waiting for completion",
         default: false,

package/dist/commands/env/add.d.ts

@@ -0,0 +1,12 @@
+import BaseCommand from "../../lib/base-command";
+export default class EnvAdd extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        environment: import("@oclif/core/lib/interfaces/parser").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/env/add.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const core_1 = require("@oclif/core");
+const base_command_1 = tslib_1.__importDefault(require("../../lib/base-command"));
+const services_1 = require("../../lib/api/services");
+const environments_1 = require("../../lib/environments");
+const upgrade_1 = require("../../lib/upgrade");
+class EnvAdd extends base_command_1.default {
+    async run() {
+        const { flags } = await this.parse(EnvAdd);
+        const service = await (0, environments_1.linkedService)(this);
+        if (await services_1.envApi.get(service.id, "staging")) {
+            this.log(`"${service.name}" already has staging. Deploy to it with 'apso deploy --env staging'.`);
+            return;
+        }
+        const ok = await (0, environments_1.confirmOrExit)(this, flags.yes, `Add staging to "${service.name}"? This starts the paid staging add-on.`);
+        if (!ok)
+            return this.log("Cancelled.");
+        await (0, upgrade_1.withUpgradeRetry)(() => services_1.envApi.addStaging(service.id), (0, environments_1.pageContext)(service));
+        this.log(`Staging is being created for "${service.name}". Deploy to it with 'apso deploy --env staging'.`);
+    }
+}
+EnvAdd.description = "Add a staging environment to the linked service. It gets its own stack, URL and database branch, and starts the paid staging add-on.";
+EnvAdd.examples = [`$ apso env add staging`, `$ apso env add staging --yes`];
+EnvAdd.args = {
+    environment: core_1.Args.string({ description: "Environment to add", options: ["staging"], required: true }),
+};
+EnvAdd.flags = {
+    yes: core_1.Flags.boolean({ char: "y", description: "Skip the confirmation prompt", default: false }),
+};
+exports.default = EnvAdd;

package/dist/commands/env/list.d.ts

@@ -0,0 +1,9 @@
+import BaseCommand from "../../lib/base-command";
+export default class EnvList extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/env/list.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const core_1 = require("@oclif/core");
+const base_command_1 = tslib_1.__importDefault(require("../../lib/base-command"));
+const services_1 = require("../../lib/api/services");
+const environments_1 = require("../../lib/environments");
+class EnvList extends base_command_1.default {
+    async run() {
+        var _a;
+        const { flags } = await this.parse(EnvList);
+        const service = await (0, environments_1.linkedService)(this);
+        const envs = await services_1.envApi.list(service.id);
+        if (flags.json) {
+            this.log(JSON.stringify(envs, null, 2));
+            return;
+        }
+        // Production's row appears with the first deploy; until then say so rather than print nothing.
+        if (!envs.some((e) => e.environment === "production")) {
+            this.log(`${"production".padEnd(12)}${"not deployed yet".padEnd(22)}-`);
+        }
+        for (const e of envs) {
+            this.log(`${e.environment.padEnd(12)}${(e.buildStatus || e.status || "-").padEnd(22)}${(_a = e.url) !== null && _a !== void 0 ? _a : "-"}`);
+        }
+        if (!envs.some((e) => e.environment === "staging")) {
+            this.log("\nNo staging environment. Add one with 'apso env add staging'.");
+        }
+    }
+}
+EnvList.description = "List the linked service's environments (production, staging)";
+EnvList.examples = [`$ apso env list`, `$ apso env list --json`];
+EnvList.flags = {
+    json: core_1.Flags.boolean({ description: "Output as JSON", default: false }),
+};
+exports.default = EnvList;

package/dist/commands/env/remove.d.ts

@@ -0,0 +1,12 @@
+import BaseCommand from "../../lib/base-command";
+export default class EnvRemove extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        environment: import("@oclif/core/lib/interfaces/parser").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/env/remove.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const core_1 = require("@oclif/core");
+const base_command_1 = tslib_1.__importDefault(require("../../lib/base-command"));
+const services_1 = require("../../lib/api/services");
+const environments_1 = require("../../lib/environments");
+class EnvRemove extends base_command_1.default {
+    async run() {
+        const { flags } = await this.parse(EnvRemove);
+        const service = await (0, environments_1.linkedService)(this);
+        if (!(await services_1.envApi.get(service.id, "staging"))) {
+            this.log(`"${service.name}" has no staging environment.`);
+            return;
+        }
+        const ok = await (0, environments_1.confirmOrExit)(this, flags.yes, `Tear down staging for "${service.name}"? Its stack and database branch are deleted.`);
+        if (!ok)
+            return this.log("Cancelled.");
+        await services_1.envApi.removeStaging(service.id);
+        this.log("Staging is being torn down. Production is unchanged.");
+    }
+}
+EnvRemove.description = "Tear down the linked service's staging environment and stop the add-on. Production is untouched.";
+EnvRemove.examples = [`$ apso env remove staging`, `$ apso env remove staging --yes`];
+EnvRemove.args = {
+    environment: core_1.Args.string({ description: "Environment to remove", options: ["staging"], required: true }),
+};
+EnvRemove.flags = {
+    yes: core_1.Flags.boolean({ char: "y", description: "Skip the confirmation prompt", default: false }),
+};
+exports.default = EnvRemove;

package/dist/commands/open.d.ts

@@ -3,6 +3,7 @@ export default class Open extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        env: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         endpoint: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         dashboard: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };

package/dist/commands/open.js

@@ -8,6 +8,7 @@ const base_command_1 = tslib_1.__importDefault(require("../lib/base-command"));
 const config_1 = require("../lib/config");
 const config_2 = require("../lib/config");
 const services_1 = require("../lib/api/services");
+const environments_1 = require("../lib/environments");
 class Open extends base_command_1.default {
     async run() {
         const { flags } = await this.parse(Open);
@@ -24,15 +25,18 @@ class Open extends base_command_1.default {
         if (flags.endpoint) {
             // Open the live API endpoint
             const service = await services_1.servicesApi.get(link.workspaceSlug, link.serviceSlug);
-            if (!service.endpoint) {
-                this.error("Service has no endpoint. Deploy first with 'apso deploy'.");
+            const env = (0, environments_1.asEnv)(flags.env);
+            const row = env === "production" ? undefined : await services_1.envApi.get(service.id, env);
+            const endpoint = row ? row.url : service.endpoint;
+            if (!endpoint) {
+                this.error(`Service has no ${env} endpoint. Deploy first with 'apso deploy --env ${env}'.`);
             }
-            this.log(`Opening endpoint: ${service.endpoint}`);
-            openUrl(service.endpoint);
+            this.log(`Opening endpoint: ${endpoint}`);
+            openUrl(endpoint);
         }
         else {
             // Open the dashboard (default)
-            const dashboardUrl = `${config.webUrl}/workspaces/${link.workspaceSlug}/services/${link.serviceSlug}`;
+            const dashboardUrl = `${config.webUrl}/${link.workspaceSlug}/services/${link.serviceId}/dashboard`;
             this.log(`Opening dashboard: ${dashboardUrl}`);
             openUrl(dashboardUrl);
         }
@@ -43,8 +47,10 @@ Open.examples = [
     `$ apso open`,
     `$ apso open --endpoint`,
     `$ apso open --dashboard`,
+    `$ apso open --endpoint --env staging`,
 ];
 Open.flags = {
+    env: environments_1.envFlag,
     endpoint: core_1.Flags.boolean({
         char: "e",
         description: "Open the service API endpoint",

package/dist/commands/promote.d.ts

@@ -0,0 +1,14 @@
+import BaseCommand from "../lib/base-command";
+import { type PromotePreview } from "../lib/api/services";
+export default class Promote extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        "dry-run": import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        "no-wait": import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}
+export declare function describePreview(p: PromotePreview): string;

package/dist/commands/promote.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describePreview = void 0;
+const tslib_1 = require("tslib");
+const core_1 = require("@oclif/core");
+const base_command_1 = tslib_1.__importDefault(require("../lib/base-command"));
+const services_1 = require("../lib/api/services");
+const environments_1 = require("../lib/environments");
+const upgrade_1 = require("../lib/upgrade");
+const spinner_1 = require("../lib/utils/spinner");
+class Promote extends base_command_1.default {
+    async run() {
+        const { flags } = await this.parse(Promote);
+        const service = await (0, environments_1.linkedService)(this);
+        const preview = await services_1.envApi.promotePreview(service.id);
+        if (flags.json)
+            this.log(JSON.stringify(preview, null, 2));
+        else
+            this.log(describePreview(preview));
+        if (preview.blocked)
+            this.error(`Promote blocked: ${preview.blocked}`);
+        if (flags["dry-run"])
+            return;
+        const ok = await (0, environments_1.confirmOrExit)(this, flags.yes, `Promote staging to production for "${service.name}"?`);
+        if (!ok)
+            return this.log("Cancelled.");
+        await (0, upgrade_1.withUpgradeRetry)(() => services_1.envApi.promote(service.id), (0, environments_1.pageContext)(service));
+        if (flags["no-wait"]) {
+            this.log("Promote started. Run 'apso status' to check progress.");
+            return;
+        }
+        const spinner = await (0, spinner_1.createSpinner)("Promoting...");
+        spinner.start();
+        const result = await services_1.buildApi.waitForCompletion(service.id, {
+            onProgress: (s) => {
+                spinner.text = `Promote status: ${s.status}...`;
+            },
+        });
+        if (result.status === "success") {
+            spinner.succeed("Production now runs staging's build.");
+        }
+        else {
+            spinner.fail("Promote failed. Production is unchanged.");
+            this.exit(1);
+        }
+    }
+}
+Promote.description = "Promote staging to production. Production runs the image staging runs now, with no rebuild. Stops when the platform blocks the promote.";
+Promote.examples = [
+    `$ apso promote`,
+    `$ apso promote --dry-run`,
+    `$ apso promote --dry-run --json`,
+    `$ apso promote --yes`,
+];
+Promote.flags = {
+    yes: core_1.Flags.boolean({ char: "y", description: "Skip the confirmation prompt", default: false }),
+    "dry-run": core_1.Flags.boolean({ description: "Show what would be promoted and stop", default: false }),
+    json: core_1.Flags.boolean({ description: "Print the preview as JSON", default: false }),
+    "no-wait": core_1.Flags.boolean({ description: "Start the promote without waiting for it to finish", default: false }),
+};
+exports.default = Promote;
+function describePreview(p) {
+    const lines = [`Commits: ${p.commits.length}`];
+    for (const c of p.commits.slice(0, 20))
+        lines.push(`  ${c.sha.slice(0, 7)} ${c.message.split("\n")[0]}`);
+    lines.push(`Migrations: ${p.migrations.length > 0 ? p.migrations.join(", ") : "none"}`);
+    if (p.missingEnvVars.length > 0)
+        lines.push(`Missing in production: ${p.missingEnvVars.join(", ")}`);
+    return lines.join("\n");
+}
+exports.describePreview = describePreview;

package/dist/commands/status.d.ts

@@ -2,6 +2,8 @@ import BaseCommand from "../lib/base-command";
 export default class Status extends BaseCommand {
     static description: string;
     static examples: string[];
-    static flags: {};
+    static flags: {
+        env: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+    };
     run(): Promise<void>;
 }

package/dist/commands/status.js

@@ -4,8 +4,11 @@ const tslib_1 = require("tslib");
 const base_command_1 = tslib_1.__importDefault(require("../lib/base-command"));
 const config_1 = require("../lib/config");
 const services_1 = require("../lib/api/services");
+const environments_1 = require("../lib/environments");
 class Status extends base_command_1.default {
     async run() {
+        const { flags } = await this.parse(Status);
+        const env = (0, environments_1.asEnv)(flags.env);
         // Auth guard
         if (!config_1.credentials.isValid()) {
             this.error("Not logged in. Run 'apso login' first.");
@@ -19,6 +22,21 @@ class Status extends base_command_1.default {
         const service = await services_1.servicesApi.get(link.workspaceId, link.serviceSlug);
         this.log(`Service: ${service.name} (${service.slug})`);
         this.log(`Workspace: ${link.workspaceSlug}`);
+        this.log(`Environment: ${env}`);
+        // Staging is its own row (stack, URL, build): show it and stop.
+        if (env !== "production") {
+            const row = await services_1.envApi.get(service.id, env);
+            if (!row) {
+                this.error(`"${service.name}" has no ${env} environment. Run 'apso env add ${env}'.`);
+            }
+            this.log(`Status: ${row.status || "-"}`);
+            this.log(`Build: ${row.buildStatus || "-"}`);
+            if (row.url)
+                this.log(`Endpoint: ${row.url}`);
+            if (row.lastDeployedAt)
+                this.log(`Last deployed: ${new Date(row.lastDeployedAt).toLocaleString()}`);
+            return;
+        }
         this.log(`Status: ${service.status}`);
         // Distinguish the account-level GitHub connection from this service's repo:
         // "GitHub: not connected" was misleading when the account WAS connected but
@@ -55,6 +73,6 @@ class Status extends base_command_1.default {
     }
 }
 Status.description = "Show the current service and latest build status";
-Status.examples = [`$ apso status`];
-Status.flags = {};
+Status.examples = [`$ apso status`, `$ apso status --env staging`];
+Status.flags = { env: environments_1.envFlag };
 exports.default = Status;

package/dist/lib/api/client.d.ts

@@ -9,6 +9,12 @@
  * - Timeout handling
  */
 import { ApiRequestOptions } from "./types";
+/**
+ * Refusals the user resolves in the web app, and where: "service" is the
+ * service's Deployments page (size and staging), "billing" the workspace's
+ * Billing page.
+ */
+export declare const APP_FIX_PAGES: Record<string, "service" | "billing">;
 /**
  * Custom error class for API errors
  */

package/dist/lib/api/client.js

@@ -10,7 +10,7 @@
  * - Timeout handling
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.api = exports.apiRequest = exports.checkNetworkConnectivity = exports.ApiClientError = void 0;
+exports.api = exports.apiRequest = exports.checkNetworkConnectivity = exports.ApiClientError = exports.APP_FIX_PAGES = void 0;
 const config_1 = require("../config");
 /**
  * Default request timeout in milliseconds
@@ -24,6 +24,17 @@ const MAX_RETRIES = 3;
  * Base delay for exponential backoff in milliseconds
  */
 const BACKOFF_BASE_DELAY = 1000;
+/**
+ * Refusals the user resolves in the web app, and where: "service" is the
+ * service's Deployments page (size and staging), "billing" the workspace's
+ * Billing page.
+ */
+exports.APP_FIX_PAGES = {
+    STAGING_REQUIRES_PAID_SERVICE: "service",
+    STAGING_ADDON_REQUIRED: "service",
+    STAGING_ADDON_PURCHASE_FAILED: "service",
+    SERVICE_SUSPENDED: "billing",
+};
 /**
  * Custom error class for API errors
  */
@@ -45,7 +56,9 @@ class ApiClientError extends Error {
      * upgrading (e.g. the free-tier service or deploy limit).
      */
     isLimitError() {
-        return (this.statusCode === 403 &&
+        if (this.code && this.code in exports.APP_FIX_PAGES)
+            return true;
+        return ((this.statusCode === 403 || this.statusCode === 402) &&
             (this.code === "SERVICE_LIMIT_REACHED" ||
                 this.code === "LIMIT_REACHED" ||
                 Boolean(this.upgradeUrl)));
@@ -306,7 +319,12 @@ async function apiRequest(path, options = {}) {
             }
             // Client errors - don't retry
             const limit = extractLimitInfo(errorData);
-            const clientError = new ApiClientError(limit.message || errorData.message || "Request failed", response.status, errorData.details);
+            // The app's API routes put their sentence in `.error`; the backend uses `.message`.
+            const appError = errorData.error;
+            const clientError = new ApiClientError(limit.message ||
+                errorData.message ||
+                (typeof appError === "string" ? appError : undefined) ||
+                "Request failed", response.status, errorData.details);
             clientError.code = limit.code;
             clientError.upgradeUrl = limit.upgradeUrl;
             throw clientError;

package/dist/lib/api/services.d.ts

@@ -84,16 +84,54 @@ export declare const schemaApi: {
  */
 export declare const buildApi: {
     /** Trigger a deploy for the linked service (POST /api/services/:id/deploy). */
-    trigger(_workspaceSlug: string, serviceSlugOrId: string): Promise<BuildStatus>;
-    /** No dedicated builds resource; derive status from the service record. */
-    getStatus(serviceId: string): Promise<BuildStatus>;
+    trigger(_workspaceSlug: string, serviceSlugOrId: string, env?: ServiceEnv): Promise<BuildStatus>;
+    /** No dedicated builds resource: production reads the service record, staging its own environment row. */
+    getStatus(serviceId: string, env?: ServiceEnv): Promise<BuildStatus>;
     getLatest(_workspaceSlug: string, serviceSlugOrId: string): Promise<BuildStatus | null>;
     waitForCompletion(serviceId: string, options?: {
         maxWait?: number | undefined;
         pollInterval?: number | undefined;
         onProgress?: ((status: BuildStatus) => void) | undefined;
+        env?: ServiceEnv | undefined;
     } | undefined): Promise<BuildStatus>;
 };
+/** Maps a platform build_status (service record or environment row) to the CLI's four states. */
+export declare function toBuildStatus(serviceId: string, buildStatus: unknown, updatedAt?: string): BuildStatus;
+/**
+ * Environments API. Each environment is a ServiceDeployment row with its own
+ * stack, URL, logs and database branch. Production always exists; staging is
+ * an add-on that `addStaging` starts (and bills) and `removeStaging` tears down.
+ */
+export type ServiceEnv = "production" | "staging";
+export declare const SERVICE_ENVS: ServiceEnv[];
+export interface Environment {
+    id: string;
+    environment: string;
+    status: string;
+    buildStatus?: string;
+    url?: string;
+    lastDeployedAt?: string;
+    updatedAt?: string;
+}
+export interface PromotePreview {
+    blocked: string | null;
+    commits: {
+        sha: string;
+        message: string;
+        author?: string;
+        date?: string;
+    }[];
+    missingEnvVars: string[];
+    migrations: string[];
+}
+export declare const envApi: {
+    list(serviceId: string): Promise<Environment[]>;
+    get(serviceId: string, env: ServiceEnv): Promise<Environment | undefined>;
+    addStaging(serviceId: string): Promise<Raw>;
+    removeStaging(serviceId: string): Promise<Raw>;
+    promotePreview(serviceId: string): Promise<PromotePreview>;
+    promote(serviceId: string): Promise<Raw>;
+};
 /**
  * GitHub API
  */

package/dist/lib/api/services.js

@@ -12,7 +12,7 @@
  * below.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.codeApi = exports.githubApi = exports.buildApi = exports.schemaApi = exports.servicesApi = exports.workspacesApi = exports.authApi = void 0;
+exports.codeApi = exports.githubApi = exports.envApi = exports.SERVICE_ENVS = exports.toBuildStatus = exports.buildApi = exports.schemaApi = exports.servicesApi = exports.workspacesApi = exports.authApi = void 0;
 const client_1 = require("./client");
 function adaptWorkspace(raw) {
     var _a, _b, _c, _d;
@@ -236,14 +236,20 @@ function adaptSchemaFromService(raw) {
  */
 exports.buildApi = {
     /** Trigger a deploy for the linked service (POST /api/services/:id/deploy). */
-    async trigger(_workspaceSlug, serviceSlugOrId) {
+    async trigger(_workspaceSlug, serviceSlugOrId, env = "production") {
         const id = await resolveServiceId(serviceSlugOrId);
-        await client_1.api.post(`/api/services/${id}/deploy`, { target: "apso" });
-        return buildStatusFromService(id);
+        await client_1.api.post(`/api/services/${id}/deploy`, { target: "apso", environment: env });
+        return this.getStatus(id, env);
     },
-    /** No dedicated builds resource; derive status from the service record. */
-    async getStatus(serviceId) {
-        return buildStatusFromService(serviceId);
+    /** No dedicated builds resource: production reads the service record, staging its own environment row. */
+    async getStatus(serviceId, env = "production") {
+        var _a;
+        if (env === "production")
+            return buildStatusFromService(serviceId);
+        const row = await exports.envApi.get(serviceId, env);
+        if (!row)
+            throw new Error(`This service has no ${env} environment. Run 'apso env add ${env}'.`);
+        return toBuildStatus(serviceId, (_a = row.buildStatus) !== null && _a !== void 0 ? _a : row.status, row.updatedAt);
     },
     async getLatest(_workspaceSlug, serviceSlugOrId) {
         const id = await resolveServiceId(serviceSlugOrId);
@@ -256,7 +262,7 @@ exports.buildApi = {
         const startTime = Date.now();
         /* eslint-disable no-await-in-loop */
         while (Date.now() - startTime < maxWait) {
-            const status = await this.getStatus(serviceId);
+            const status = await this.getStatus(serviceId, options === null || options === void 0 ? void 0 : options.env);
             if (options === null || options === void 0 ? void 0 : options.onProgress)
                 options.onProgress(status);
             if (status.status === "success" || status.status === "failed")
@@ -270,18 +276,59 @@ exports.buildApi = {
     },
 };
 async function buildStatusFromService(serviceId) {
-    var _a, _b, _c;
+    var _a;
     const raw = await client_1.api.get(`/api/services/${serviceId}`);
-    const b = String((_a = raw.build_status) !== null && _a !== void 0 ? _a : "").toLowerCase();
+    return toBuildStatus(String(raw.id), raw.build_status, (_a = raw.updated_at) !== null && _a !== void 0 ? _a : raw.created_at);
+}
+/** Maps a platform build_status (service record or environment row) to the CLI's four states. */
+function toBuildStatus(serviceId, buildStatus, updatedAt) {
+    const b = String(buildStatus !== null && buildStatus !== void 0 ? buildStatus : "").toLowerCase();
     const status = b === "ready" ? "success" : b === "failed" || b === "error" ? "failed" : b === "new" || b === "" ? "pending" : "building";
     return {
-        id: String(raw.id),
-        serviceId: String(raw.id),
+        id: serviceId,
+        serviceId,
         status,
-        startedAt: (_c = (_b = raw.updated_at) !== null && _b !== void 0 ? _b : raw.created_at) !== null && _c !== void 0 ? _c : new Date().toISOString(),
-        completedAt: status === "success" || status === "failed" ? raw.updated_at : undefined,
+        startedAt: updatedAt !== null && updatedAt !== void 0 ? updatedAt : new Date().toISOString(),
+        completedAt: status === "success" || status === "failed" ? updatedAt : undefined,
     };
 }
+exports.toBuildStatus = toBuildStatus;
+exports.SERVICE_ENVS = ["production", "staging"];
+exports.envApi = {
+    async list(serviceId) {
+        var _a;
+        const raw = await client_1.api.get(`/api/services/${serviceId}/deployments`);
+        const rows = Array.isArray(raw) ? raw : (_a = raw === null || raw === void 0 ? void 0 : raw.data) !== null && _a !== void 0 ? _a : [];
+        return rows.map((r) => {
+            var _a, _b, _c, _d, _e;
+            return ({
+                id: String(r.id),
+                environment: String(r.environment_type),
+                status: String((_a = r.deployment_status) !== null && _a !== void 0 ? _a : ""),
+                buildStatus: (_b = r.build_status) !== null && _b !== void 0 ? _b : undefined,
+                url: (_c = r.deployment_url) !== null && _c !== void 0 ? _c : undefined,
+                lastDeployedAt: (_d = r.last_deployed_at) !== null && _d !== void 0 ? _d : undefined,
+                updatedAt: (_e = r.updated_at) !== null && _e !== void 0 ? _e : undefined,
+            });
+        });
+    },
+    async get(serviceId, env) {
+        const envs = await this.list(serviceId);
+        return envs.find((e) => e.environment === env);
+    },
+    addStaging(serviceId) {
+        return client_1.api.post(`/api/services/${serviceId}/environments/staging`);
+    },
+    removeStaging(serviceId) {
+        return client_1.api.delete(`/api/services/${serviceId}/environments/staging`);
+    },
+    promotePreview(serviceId) {
+        return client_1.api.get(`/api/services/${serviceId}/environments/promote-preview`);
+    },
+    promote(serviceId) {
+        return client_1.api.post(`/api/services/${serviceId}/promote`);
+    },
+};
 /**
  * GitHub API
  */

package/dist/lib/environments.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "@oclif/core";
+import { type ServiceEnv } from "./api/services";
+import type { Service } from "./api/types";
+import type { PageContext } from "./upgrade";
+export declare const envFlag: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+export declare const asEnv: (value: string | undefined) => ServiceEnv;
+export declare function linkedService(cmd: Command): Promise<Service>;
+export declare function pageContext(service: Service): PageContext;
+export declare function confirmOrExit(cmd: Command, yes: boolean, question: string): Promise<boolean>;

package/dist/lib/environments.js

@@ -0,0 +1,67 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirmOrExit = exports.pageContext = exports.linkedService = exports.asEnv = exports.envFlag = void 0;
+const core_1 = require("@oclif/core");
+const config_1 = require("./config");
+const services_1 = require("./api/services");
+const interactive_1 = require("./utils/interactive");
+// --env for commands that act on one environment. Production is the default, so existing scripts behave as before.
+exports.envFlag = core_1.Flags.string({
+    description: "Environment to target",
+    options: services_1.SERVICE_ENVS,
+    default: "production",
+});
+const asEnv = (value) => value === "staging" ? "staging" : "production";
+exports.asEnv = asEnv;
+// The linked service, after the login and link checks every platform command makes.
+async function linkedService(cmd) {
+    if (!config_1.credentials.isValid())
+        cmd.error("Not logged in. Run 'apso login' first.");
+    const link = config_1.projectLink.read();
+    if (!link)
+        cmd.error("Project not linked. Run 'apso link' first.");
+    return services_1.servicesApi.get(link.workspaceId, link.serviceSlug);
+}
+exports.linkedService = linkedService;
+// Where the linked service lives in the web app, for links to the page that fixes a refusal.
+function pageContext(service) {
+    var _a;
+    return { workspaceSlug: (_a = config_1.projectLink.read()) === null || _a === void 0 ? void 0 : _a.workspaceSlug, serviceId: service.id };
+}
+exports.pageContext = pageContext;
+// Asks before a step that costs money or replaces something; headless runs must pass --yes.
+async function confirmOrExit(cmd, yes, question) {
+    if (yes)
+        return true;
+    if (!(0, interactive_1.isInteractive)())
+        cmd.error((0, interactive_1.missingFlag)(`${question} Pass --yes to proceed.`));
+    const inquirer = await Promise.resolve().then(() => __importStar(require("inquirer")));
+    const { ok } = await inquirer.default.prompt([
+        { type: "confirm", name: "ok", message: question, default: false },
+    ]);
+    return ok;
+}
+exports.confirmOrExit = confirmOrExit;

package/dist/lib/upgrade.d.ts

@@ -7,13 +7,23 @@
  * "you've hit a limit, upgrade?" flow developers expect from modern CLIs.
  */
 import { ApiClientError } from "./api/client";
+/** Where the user is when the refusal happened, so the link can go to the exact page. */
+export interface PageContext {
+    workspaceSlug?: string;
+    serviceId?: string;
+}
+/** The web app page that resolves this refusal, and how to name it in a prompt. */
+export declare function fixPage(error: ApiClientError, ctx?: PageContext): {
+    url: string;
+    label: string;
+};
 /**
- * Prompt the user to upgrade after a limit error, open the upgrade page, and
- * wait for them to finish. Returns true if the caller should retry the action.
+ * Prompt the user to resolve a plan or billing refusal in the web app, open the
+ * page, and wait for them to finish. Returns true if the caller should retry.
  */
-export declare function promptUpgrade(error: ApiClientError): Promise<boolean>;
+export declare function promptUpgrade(error: ApiClientError, ctx?: PageContext): Promise<boolean>;
 /**
  * Run an action; if it fails with an upgradeable plan-limit error, offer to
  * upgrade and retry once.
  */
-export declare function withUpgradeRetry<T>(action: () => Promise<T>): Promise<T>;
+export declare function withUpgradeRetry<T>(action: () => Promise<T>, ctx?: PageContext): Promise<T>;

package/dist/lib/upgrade.js

@@ -8,7 +8,7 @@
  * "you've hit a limit, upgrade?" flow developers expect from modern CLIs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withUpgradeRetry = exports.promptUpgrade = void 0;
+exports.withUpgradeRetry = exports.promptUpgrade = exports.fixPage = void 0;
 const tslib_1 = require("tslib");
 const child_process_1 = require("child_process");
 const inquirer_1 = tslib_1.__importDefault(require("inquirer"));
@@ -29,13 +29,31 @@ function openBrowser(url) {
         (0, child_process_1.exec)(command, () => resolve());
     });
 }
+/** The web app page that resolves this refusal, and how to name it in a prompt. */
+function fixPage(error, ctx = {}) {
+    const web = config_1.globalConfig.read().webUrl;
+    const where = error.code ? client_1.APP_FIX_PAGES[error.code] : undefined;
+    if (where === "service" && ctx.workspaceSlug && ctx.serviceId) {
+        return {
+            url: `${web}/${ctx.workspaceSlug}/services/${ctx.serviceId}/deployments`,
+            label: "the service's Deployments page",
+        };
+    }
+    if (where === "billing" && ctx.workspaceSlug) {
+        return { url: `${web}/${ctx.workspaceSlug}/billing`, label: "Billing" };
+    }
+    return {
+        url: `${web}${error.upgradeUrl || "/billing/upgrade"}`,
+        label: "the upgrade page",
+    };
+}
+exports.fixPage = fixPage;
 /**
- * Prompt the user to upgrade after a limit error, open the upgrade page, and
- * wait for them to finish. Returns true if the caller should retry the action.
+ * Prompt the user to resolve a plan or billing refusal in the web app, open the
+ * page, and wait for them to finish. Returns true if the caller should retry.
  */
-async function promptUpgrade(error) {
-    const config = config_1.globalConfig.read();
-    const upgradeUrl = `${config.webUrl}${error.upgradeUrl || "/billing/upgrade"}`;
+async function promptUpgrade(error, ctx = {}) {
+    const { url: upgradeUrl, label } = fixPage(error, ctx);
     console.log("");
     console.log(`  ⚠  ${error.message || "You've reached a plan limit."}`);
     console.log("");
@@ -43,12 +61,12 @@ async function promptUpgrade(error) {
         {
             type: "confirm",
             name: "proceed",
-            message: "Open the upgrade page in your browser?",
+            message: `Open ${label} in your browser?`,
             default: true,
         },
     ]);
     if (!proceed) {
-        console.log(`  You can upgrade any time at: ${upgradeUrl}`);
+        console.log(`  You can do this any time at: ${upgradeUrl}`);
         return false;
     }
     console.log("");
@@ -59,7 +77,7 @@ async function promptUpgrade(error) {
         {
             type: "confirm",
             name: "done",
-            message: "Press enter once your upgrade is complete to retry",
+            message: "Press enter once you are done there to retry",
             default: true,
         },
     ]);
@@ -70,7 +88,7 @@ exports.promptUpgrade = promptUpgrade;
  * Run an action; if it fails with an upgradeable plan-limit error, offer to
  * upgrade and retry once.
  */
-async function withUpgradeRetry(action) {
+async function withUpgradeRetry(action, ctx = {}) {
     try {
         return await action();
     }
@@ -79,10 +97,10 @@ async function withUpgradeRetry(action) {
             // Headless (agent/CI): never open a browser or prompt — surface the limit
             // as a clear error with the upgrade URL so the caller can act on it.
             if (!(0, interactive_1.isInteractive)()) {
-                const upgradeUrl = `${config_1.globalConfig.read().webUrl}${error.upgradeUrl || "/billing/upgrade"}`;
-                throw new Error(`${error.message || "Plan limit reached."} Upgrade at ${upgradeUrl}`);
+                const { url } = fixPage(error, ctx);
+                throw new Error(`${(error.message || "Plan limit reached").replace(/\.?$/, ".")} Resolve it at ${url}`);
             }
-            const retry = await promptUpgrade(error);
+            const retry = await promptUpgrade(error, ctx);
             if (retry) {
                 return action();
             }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@apso/cli",
-  "version": "0.46.4",
+  "version": "0.47.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@apso/cli",
-      "version": "0.46.4",
+      "version": "0.47.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@apso/schema-tools": "^0.2.0",

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.46.4",
+  "version": "0.47.1",
   "commands": {
     "config": {
       "id": "config",
@@ -49,9 +49,21 @@
         "$ apso deploy",
         "$ apso deploy --yes",
         "$ apso deploy --skip-migrate",
-        "$ apso deploy --no-wait"
+        "$ apso deploy --no-wait",
+        "$ apso deploy --env staging"
       ],
       "flags": {
+        "env": {
+          "name": "env",
+          "type": "option",
+          "description": "Environment to target",
+          "multiple": false,
+          "options": [
+            "production",
+            "staging"
+          ],
+          "default": "production"
+        },
         "no-wait": {
           "name": "no-wait",
           "type": "boolean",
@@ -464,9 +476,21 @@
       "examples": [
         "$ apso open",
         "$ apso open --endpoint",
-        "$ apso open --dashboard"
+        "$ apso open --dashboard",
+        "$ apso open --endpoint --env staging"
       ],
       "flags": {
+        "env": {
+          "name": "env",
+          "type": "option",
+          "description": "Environment to target",
+          "multiple": false,
+          "options": [
+            "production",
+            "staging"
+          ],
+          "default": "production"
+        },
         "endpoint": {
           "name": "endpoint",
           "type": "boolean",
@@ -515,6 +539,50 @@
       },
       "args": {}
     },
+    "promote": {
+      "id": "promote",
+      "description": "Promote staging to production. Production runs the image staging runs now, with no rebuild. Stops when the platform blocks the promote.",
+      "strict": true,
+      "pluginName": "@apso/cli",
+      "pluginAlias": "@apso/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "hiddenAliases": [],
+      "examples": [
+        "$ apso promote",
+        "$ apso promote --dry-run",
+        "$ apso promote --dry-run --json",
+        "$ apso promote --yes"
+      ],
+      "flags": {
+        "yes": {
+          "name": "yes",
+          "type": "boolean",
+          "char": "y",
+          "description": "Skip the confirmation prompt",
+          "allowNo": false
+        },
+        "dry-run": {
+          "name": "dry-run",
+          "type": "boolean",
+          "description": "Show what would be promoted and stop",
+          "allowNo": false
+        },
+        "json": {
+          "name": "json",
+          "type": "boolean",
+          "description": "Print the preview as JSON",
+          "allowNo": false
+        },
+        "no-wait": {
+          "name": "no-wait",
+          "type": "boolean",
+          "description": "Start the promote without waiting for it to finish",
+          "allowNo": false
+        }
+      },
+      "args": {}
+    },
     "status": {
       "id": "status",
       "description": "Show the current service and latest build status",
@@ -525,9 +593,22 @@
       "aliases": [],
       "hiddenAliases": [],
       "examples": [
-        "$ apso status"
+        "$ apso status",
+        "$ apso status --env staging"
       ],
-      "flags": {},
+      "flags": {
+        "env": {
+          "name": "env",
+          "type": "option",
+          "description": "Environment to target",
+          "multiple": false,
+          "options": [
+            "production",
+            "staging"
+          ],
+          "default": "production"
+        }
+      },
       "args": {}
     },
     "unlink": {
@@ -629,6 +710,95 @@
       },
       "args": {}
     },
+    "env:add": {
+      "id": "env:add",
+      "description": "Add a staging environment to the linked service. It gets its own stack, URL and database branch, and starts the paid staging add-on.",
+      "strict": true,
+      "pluginName": "@apso/cli",
+      "pluginAlias": "@apso/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "hiddenAliases": [],
+      "examples": [
+        "$ apso env add staging",
+        "$ apso env add staging --yes"
+      ],
+      "flags": {
+        "yes": {
+          "name": "yes",
+          "type": "boolean",
+          "char": "y",
+          "description": "Skip the confirmation prompt",
+          "allowNo": false
+        }
+      },
+      "args": {
+        "environment": {
+          "name": "environment",
+          "description": "Environment to add",
+          "required": true,
+          "options": [
+            "staging"
+          ]
+        }
+      }
+    },
+    "env:list": {
+      "id": "env:list",
+      "description": "List the linked service's environments (production, staging)",
+      "strict": true,
+      "pluginName": "@apso/cli",
+      "pluginAlias": "@apso/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "hiddenAliases": [],
+      "examples": [
+        "$ apso env list",
+        "$ apso env list --json"
+      ],
+      "flags": {
+        "json": {
+          "name": "json",
+          "type": "boolean",
+          "description": "Output as JSON",
+          "allowNo": false
+        }
+      },
+      "args": {}
+    },
+    "env:remove": {
+      "id": "env:remove",
+      "description": "Tear down the linked service's staging environment and stop the add-on. Production is untouched.",
+      "strict": true,
+      "pluginName": "@apso/cli",
+      "pluginAlias": "@apso/cli",
+      "pluginType": "core",
+      "aliases": [],
+      "hiddenAliases": [],
+      "examples": [
+        "$ apso env remove staging",
+        "$ apso env remove staging --yes"
+      ],
+      "flags": {
+        "yes": {
+          "name": "yes",
+          "type": "boolean",
+          "char": "y",
+          "description": "Skip the confirmation prompt",
+          "allowNo": false
+        }
+      },
+      "args": {
+        "environment": {
+          "name": "environment",
+          "description": "Environment to remove",
+          "required": true,
+          "options": [
+            "staging"
+          ]
+        }
+      }
+    },
     "github:connect": {
       "id": "github:connect",
       "description": "Connect a GitHub account to push generated code to a repo",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apso/cli",
-  "version": "0.46.4",
+  "version": "0.47.1",
   "mcpName": "io.github.apsoai/apso",
   "description": "Apso CLI",
   "author": "Apso by Mavric - @mavric",
@@ -104,6 +104,9 @@
       },
       "import": {
         "description": "Import an existing database into a local .apsorc schema"
+      },
+      "env": {
+        "description": "Manage a service's environments (production, staging)"
       }
     },
     "update": {