@getxflow/cli 0.6.6 → 0.8.0

package/README.md

@@ -18,7 +18,7 @@ else's code belongs next to it.
 |---|---|
 | `login` / `logout` / `whoami` | sign in through the browser, sign out, whose key this is and what it can do |
 | `init` / `link` | new project, link a folder to an existing one |
-| `status` / `push` / `pull` | state, sending and fetching sources |
+| `status` / `pull` | state of the sources on the server and fetching them back |
 | `deploy` / `publish` / `rollback` / `deployments` | build, publish, roll back, version history |
 | `db status` / `db migrate` | migrations from `migrations/*.sql` with a gate on destructive ones |
 | `db schema` / `db query` | tables and columns, reading data in a read-only transaction |

package/dist/bin.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const api_1 = require("./api");
 const args_1 = require("./args");
 const config_1 = require("./config");
+const credentials_1 = require("./credentials");
 const errors_1 = require("./errors");
 const help_1 = require("./help");
 const limits_1 = require("./limits");
@@ -19,6 +20,7 @@ const env_1 = require("./commands/env");
 const functions_1 = require("./commands/functions");
 const logs_1 = require("./commands/logs");
 const mcp_1 = require("./commands/mcp");
+const org_1 = require("./commands/org");
 const schedules_1 = require("./commands/schedules");
 const skills_1 = require("./commands/skills");
 const sources_1 = require("./commands/sources");
@@ -38,11 +40,21 @@ async function run(args) {
             await (0, auth_1.login)();
             return;
         case 'logout':
-            (0, auth_1.logout)();
+            (0, auth_1.logout)(rest);
             return;
         case 'whoami':
             await (0, auth_1.whoami)();
             return;
+        case 'org':
+            if (second === 'switch') {
+                (0, org_1.orgSwitch)({ ...args, words: args.words.slice(2) });
+                return;
+            }
+            if (second === undefined || second === 'list') {
+                (0, org_1.orgList)();
+                return;
+            }
+            throw new errors_1.CliError(`Unknown command: org ${second}`, 'Available: list and switch');
         case 'templates':
             await (0, projects_1.templates)();
             return;
@@ -155,9 +167,6 @@ async function run(args) {
         case 'status':
             await (0, sources_1.status)();
             return;
-        case 'push':
-            await (0, sources_1.push)(rest);
-            return;
         case 'pull':
             await (0, sources_1.pull)(rest);
             return;
@@ -216,6 +225,9 @@ async function main() {
                 (0, ui_1.note)((0, ui_1.dim)(`  ${(0, limits_1.limitLine)(e.limit)}`));
             if (e.hint)
                 (0, ui_1.note)((0, ui_1.dim)(`  ${e.hint}`));
+            if (e.code === 'not_found' && (0, credentials_1.anyMultipleOrgs)()) {
+                (0, ui_1.note)((0, ui_1.dim)('  Several organizations are signed in: the answer may live in another one, see xflow org'));
+            }
             quiet = quiet || e.code === 'outdated_cli';
             return 1;
         }

package/dist/commands/auth.js

@@ -5,27 +5,17 @@ exports.logout = logout;
 exports.whoami = whoami;
 const node_os_1 = require("node:os");
 const api_1 = require("../api");
+const args_1 = require("../args");
 const config_1 = require("../config");
 const credentials_1 = require("../credentials");
 const errors_1 = require("../errors");
 const limits_1 = require("../limits");
 const session_1 = require("../session");
 const ui_1 = require("../ui");
-function localConfig() {
-    const root = (0, config_1.findProjectRoot)();
-    if (!root)
-        return undefined;
-    try {
-        return (0, config_1.readConfig)(root);
-    }
-    catch {
-        return undefined;
-    }
-}
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** Device flow: the key is issued after confirmation in the browser, never typed. */
 async function login() {
-    const config = localConfig();
+    const config = (0, config_1.localConfig)();
     const client = (0, session_1.anonymous)(config);
     // The machine name becomes the key label on the platform.
     const start = await (0, api_1.apiJson)(client, '/api/v1/auth/device', {
@@ -74,22 +64,55 @@ async function awaitConfirmation(client, start) {
         }
         if (poll.status === 'pending')
             continue;
-        (0, credentials_1.saveCredential)(client.apiUrl, {
-            token: poll.token,
-            organizationId: poll.organization_id,
-            projectId: poll.project_id,
-        });
-        (0, ui_1.ok)(`Signed in, the key is stored for ${client.apiUrl}`);
+        if (!poll.organization_id) {
+            throw new errors_1.CliError('The platform did not name the organization of the key', 'Try again: xflow login');
+        }
+        (0, credentials_1.saveOrgCredential)(client.apiUrl, poll.organization_id, poll.token);
+        // The key of every other stored organization stays; this one becomes active.
+        const authed = { apiUrl: client.apiUrl, token: poll.token };
+        const name = await (0, api_1.apiJson)(authed, '/api/v1/me')
+            .then((me) => me.organization.name)
+            .catch(() => null);
+        if (name)
+            (0, credentials_1.rememberOrgName)(client.apiUrl, poll.organization_id, name);
+        (0, ui_1.ok)(`Signed in to "${name ?? poll.organization_id}", the key is stored for ${client.apiUrl}`);
+        const others = (0, credentials_1.listOrgs)(client.apiUrl).length - 1;
+        if (others > 0)
+            (0, ui_1.note)((0, ui_1.dim)(`  ${others} more stored: xflow org`));
         return;
     }
 }
-function logout() {
-    const apiUrl = (0, config_1.apiUrlFor)(localConfig());
-    if ((0, credentials_1.forgetCredential)(apiUrl)) {
-        (0, ui_1.ok)(`The key for ${apiUrl} is deleted`);
+function logout(args) {
+    const apiUrl = (0, config_1.apiUrlFor)((0, config_1.localConfig)());
+    if ((0, args_1.flagBool)(args, 'all')) {
+        if ((0, credentials_1.forgetAllOrgs)(apiUrl))
+            (0, ui_1.ok)(`Every key for ${apiUrl} is deleted`);
+        else
+            (0, ui_1.warn)(`There is no stored key for ${apiUrl}`);
+        return;
     }
-    else {
-        (0, ui_1.warn)(`There is no stored key for ${apiUrl}`);
+    const orgs = (0, credentials_1.listOrgs)(apiUrl);
+    const active = orgs.find((org) => org.active);
+    if (!active) {
+        // A record from an older CLI names no organization: forget the whole address.
+        if ((0, credentials_1.forgetAllOrgs)(apiUrl))
+            (0, ui_1.ok)(`The key for ${apiUrl} is deleted`);
+        else
+            (0, ui_1.warn)(`There is no stored key for ${apiUrl}`);
+        return;
+    }
+    const { nextActive } = (0, credentials_1.forgetOrg)(apiUrl, active.organizationId);
+    (0, ui_1.ok)(`Signed out of "${active.name ?? active.organizationId}"`);
+    // Inside a folder bound to another organization the command may read as
+    // "revoke access to this project", which is not what just happened.
+    const root = (0, config_1.findProjectRoot)();
+    const boundId = root ? (0, config_1.readState)(root).organizationId : undefined;
+    if (boundId && boundId !== active.organizationId) {
+        const bound = orgs.find((org) => org.organizationId === boundId);
+        (0, ui_1.note)((0, ui_1.dim)(`  This folder is bound to "${bound?.name ?? boundId}": its key is untouched`));
+    }
+    if (nextActive) {
+        (0, ui_1.note)((0, ui_1.dim)(`  Active organization now: "${nextActive.name ?? nextActive.organizationId}". Every key: xflow logout --all`));
     }
 }
 /** Suffix for a non-active subscription. */
@@ -99,18 +122,23 @@ const SUBSCRIPTION_STATE = {
     terminated: ', the subscription is terminated',
 };
 async function whoami() {
-    const config = localConfig();
+    const config = (0, config_1.localConfig)();
     const client = (0, session_1.connect)(config);
     const me = await (0, api_1.apiJson)(client, '/api/v1/me');
     (0, ui_1.out)(`Organization: ${me.organization.name ?? me.organization.id}`);
     (0, ui_1.out)(`Key:          xfk_${me.key.prefix}… (${me.key.scopes.join(', ')})`);
     (0, ui_1.out)(`Platform:     ${client.apiUrl}`);
-    // Same condition as in connect: for an address out of xflow.json the env key is ignored.
-    if (process.env.XFLOW_TOKEN?.trim() && client.apiUrl === (0, config_1.apiUrlFor)()) {
-        (0, ui_1.note)((0, ui_1.dim)('  The key comes from XFLOW_TOKEN, the one stored in ~/.xflow is not used'));
+    (0, credentials_1.rememberOrgName)(client.apiUrl, me.organization.id, me.organization.name);
+    if (client.source === 'env') {
+        (0, ui_1.note)((0, ui_1.dim)('  The key comes from XFLOW_TOKEN, the ones stored in ~/.xflow are not used'));
+    }
+    else if (client.source === 'folder') {
+        (0, ui_1.note)((0, ui_1.dim)('  The key follows the organization this folder is bound to (.xflow/state.json)'));
     }
-    else if (!(0, credentials_1.readCredential)(client.apiUrl)) {
-        (0, ui_1.note)((0, ui_1.dim)('  The key is not stored'));
+    else {
+        const others = (0, credentials_1.listOrgs)(client.apiUrl).length - 1;
+        if (others > 0)
+            (0, ui_1.note)((0, ui_1.dim)(`  The key of the active organization, ${others} more stored: xflow org`));
     }
     if (me.billing) {
         const pkg = me.billing.package_title ? `, ${me.billing.package_title}` : '';

package/dist/commands/deploy.js

@@ -102,12 +102,12 @@ async function startBuild(client, projectId, revision, allowRemovals) {
 }
 async function deploy(args) {
     const { root, config } = (0, config_1.requireProject)();
-    const client = (0, session_1.connect)(config);
+    const client = await (0, session_1.connectProject)(root, config);
     let revision;
     if ((0, args_1.flagBool)(args, 'no-push')) {
         const server = await (0, sources_1.latestRevision)(client, config.projectId);
         if (!server) {
-            throw new errors_1.CliError('The server holds no sources', 'Send them: xflow push');
+            throw new errors_1.CliError('The server holds no sources', 'Repeat without --no-push, so that the sources go up first');
         }
         revision = server.revision;
         (0, ui_1.warn)(`Sources not sent (--no-push), the build runs from revision ${revision}`);
@@ -148,8 +148,8 @@ async function deploy(args) {
     (0, ui_1.note)((0, ui_1.dim)('  Show it to visitors: xflow publish'));
 }
 async function publish() {
-    const { config } = (0, config_1.requireProject)();
-    const client = (0, session_1.connect)(config);
+    const { root, config } = (0, config_1.requireProject)();
+    const client = await (0, session_1.connectProject)(root, config);
     (0, ui_1.step)('Publishing the current dev version');
     const result = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/publish`, { method: 'POST', timeoutMs: 120_000 });
     if (result.already_published) {
@@ -161,12 +161,12 @@ async function publish() {
     (0, ui_1.out)(result.project_url);
 }
 async function rollback(args) {
-    const { config } = (0, config_1.requireProject)();
+    const { root, config } = (0, config_1.requireProject)();
     const deployId = args.words[0];
     if (!deployId) {
         throw new errors_1.CliError('A version number is required', 'To see the versions: xflow deployments. For example: xflow rollback 481203');
     }
-    const client = (0, session_1.connect)(config);
+    const client = await (0, session_1.connectProject)(root, config);
     const result = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/rollback`, { method: 'POST', body: { deploy_id: deployId } });
     (0, ui_1.ok)(`The dev version of the project is switched to ${result.deploy_id}`);
     (0, ui_1.out)(result.project_url);
@@ -176,8 +176,8 @@ async function rollback(args) {
     (0, ui_1.note)((0, ui_1.dim)('  Visitors see it only after xflow publish'));
 }
 async function deployments() {
-    const { config } = (0, config_1.requireProject)();
-    const client = (0, session_1.connect)(config);
+    const { root, config } = (0, config_1.requireProject)();
+    const client = await (0, session_1.connectProject)(root, config);
     const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/deployments`);
     if (data.deployments.length === 0) {
         (0, ui_1.note)('No versions yet. To build and release: xflow deploy');

package/dist/commands/mcp.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshAgentKey = refreshAgentKey;
 exports.mcpInstall = mcpInstall;
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -26,6 +27,8 @@ const CLIENTS = [
         ],
         // Re-running must update the entry, not fail on it.
         reset: ['mcp', 'remove', 'xflow', '-s', 'local'],
+        // Succeeds only when an xflow entry is visible from this folder.
+        probe: ['mcp', 'get', 'xflow'],
     },
 ];
 // Output is captured, not inherited: clients may echo the added header together
@@ -33,6 +36,24 @@ const CLIENTS = [
 function hasBinary(binary) {
     return (0, spawn_1.run)(binary, ['--version']).status === 0;
 }
+/**
+ * Rewrite the key in clients that already hold an xflow entry visible from this
+ * folder. Entries are never created here: that stays with xflow mcp install.
+ */
+function refreshAgentKey(client) {
+    const url = `${client.apiUrl.replace(/\/+$/, '')}/api/mcp`;
+    let updated = false;
+    for (const target of CLIENTS) {
+        if (!hasBinary(target.binary))
+            continue;
+        if ((0, spawn_1.run)(target.binary, [...target.probe]).status !== 0)
+            continue;
+        (0, spawn_1.run)(target.binary, [...target.reset]);
+        if ((0, spawn_1.run)(target.binary, target.args(url, client.token)).status === 0)
+            updated = true;
+    }
+    return updated;
+}
 async function mcpInstall(args) {
     // The server covers the organization: the command works outside a project folder too.
     const root = (0, config_1.findProjectRoot)();

package/dist/commands/org.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orgList = orgList;
+exports.orgSwitch = orgSwitch;
+const config_1 = require("../config");
+const credentials_1 = require("../credentials");
+const errors_1 = require("../errors");
+const ui_1 = require("../ui");
+const mcp_1 = require("./mcp");
+function label(org) {
+    return org.name ?? org.organizationId;
+}
+/** Organizations of this platform address that hold a stored key. */
+function orgList() {
+    const apiUrl = (0, config_1.apiUrlFor)((0, config_1.localConfig)());
+    const orgs = (0, credentials_1.listOrgs)(apiUrl);
+    if (orgs.length === 0) {
+        if ((0, credentials_1.storedKeyInputs)(apiUrl).legacyToken) {
+            (0, ui_1.note)(`One key is stored for ${apiUrl}, its organization is unknown`);
+            (0, ui_1.note)((0, ui_1.dim)('  Sign in again to refresh it: xflow login'));
+        }
+        else {
+            (0, ui_1.note)(`No keys for ${apiUrl}. Sign in: xflow login`);
+        }
+        return;
+    }
+    (0, ui_1.table)(orgs.map((org) => [org.active ? '*' : ' ', org.name ?? '(unnamed)', org.organizationId]));
+    const root = (0, config_1.findProjectRoot)();
+    const boundId = root ? (0, config_1.readState)(root).organizationId : undefined;
+    if (boundId) {
+        const bound = orgs.find((org) => org.organizationId === boundId);
+        (0, ui_1.note)((0, ui_1.dim)(`  This folder is bound to "${bound ? label(bound) : boundId}": commands here stay in it`));
+    }
+    if (orgs.length > 1)
+        (0, ui_1.note)((0, ui_1.dim)('  Switch: xflow org switch <name or id>'));
+    (0, ui_1.note)((0, ui_1.dim)('  To add an organization, sign in to it: xflow login'));
+}
+/** Local switch of the active organization: a pointer move, no browser. */
+function orgSwitch(args) {
+    const wanted = args.words[0];
+    if (!wanted)
+        throw new errors_1.CliError('An organization is required', 'The list: xflow org');
+    const apiUrl = (0, config_1.apiUrlFor)((0, config_1.localConfig)());
+    const orgs = (0, credentials_1.listOrgs)(apiUrl);
+    if (orgs.length === 0) {
+        if ((0, credentials_1.storedKeyInputs)(apiUrl).legacyToken) {
+            throw new errors_1.CliError(`The stored key for ${apiUrl} names no organization`, 'Sign in again to refresh it: xflow login');
+        }
+        throw new errors_1.CliError(`No keys for ${apiUrl}`, 'Sign in: xflow login');
+    }
+    const byId = orgs.find((org) => org.organizationId === wanted);
+    const byName = orgs.filter((org) => (org.name ?? '').toLowerCase() === wanted.toLowerCase());
+    if (!byId && byName.length > 1) {
+        throw new errors_1.CliError(`Several organizations are named "${wanted}"`, `Use the id instead: ${byName.map((org) => org.organizationId).join(', ')}`);
+    }
+    const target = byId ?? byName[0];
+    if (!target) {
+        throw new errors_1.CliError(`No stored key for "${wanted}"`, 'The list: xflow org. To add one: xflow login');
+    }
+    if (target.active) {
+        (0, ui_1.ok)(`"${label(target)}" is already the active organization`);
+        return;
+    }
+    (0, credentials_1.setActiveOrg)(apiUrl, target.organizationId);
+    (0, ui_1.ok)(`Active organization: "${label(target)}"`);
+    const root = (0, config_1.findProjectRoot)();
+    if (root) {
+        // The agent entry of a project folder belongs to the folder's organization,
+        // so the switch leaves it alone.
+        const boundId = (0, config_1.readState)(root).organizationId;
+        if (boundId && boundId !== target.organizationId) {
+            const bound = orgs.find((org) => org.organizationId === boundId);
+            (0, ui_1.note)((0, ui_1.dim)(`  This folder is bound to "${bound ? label(bound) : boundId}": commands here stay in it`));
+        }
+        return;
+    }
+    if ((0, mcp_1.refreshAgentKey)({ apiUrl, token: target.token })) {
+        (0, ui_1.note)((0, ui_1.dim)('  The agent key here is rewritten: restart the agent session to pick it up'));
+    }
+}

package/dist/commands/projects.js

@@ -82,6 +82,8 @@ async function init(args) {
         };
         (0, config_1.writeConfig)(target, config);
         (0, config_1.ignoreStateInGit)(target);
+        if (client.organizationId)
+            (0, config_1.writeState)(target, { organizationId: client.organizationId });
     }
     catch (e) {
         (0, ui_1.note)((0, ui_1.dim)(`  The project "${project.name}" is already created (${project.id}).`));
@@ -100,12 +102,34 @@ async function init(args) {
 async function link(args) {
     const root = (0, config_1.findProjectRoot)() ?? process.cwd();
     const existing = (0, node_fs_1.existsSync)((0, node_path_1.join)(root, config_1.CONFIG_FILE)) ? (0, config_1.readConfig)(root) : undefined;
-    const client = (0, session_1.connect)(existing);
+    let client = (0, session_1.connect)(existing);
     const projectId = args.words[0];
     if (!projectId) {
         throw new errors_1.CliError('A project identifier is required', 'The list: xflow projects list');
     }
-    const card = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}`);
+    let card;
+    try {
+        card = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}`);
+    }
+    catch (e) {
+        // Project ids are unique across the platform, so a 404 under this key does
+        // not mean the project does not exist: another signed-in organization may
+        // hold it. A dead key (401/403) says even less. Ask every stored
+        // organization before giving up.
+        if (!(e instanceof api_1.ApiError && (e.status === 404 || e.status === 401 || e.status === 403)) ||
+            client.source === 'env') {
+            throw e;
+        }
+        const { hit, dead } = await (0, session_1.findProjectOrg)(client.apiUrl, projectId);
+        if (!hit) {
+            throw new errors_1.CliError(`No signed-in organization holds the project ${projectId}`, dead.length > 0
+                ? `The key of ${dead.map((d) => d.name ?? d.organizationId).join(', ')} is not working (sign in again: xflow login); the project may live there`
+                : 'Check the id (xflow projects list), or sign in to the organization that owns it: xflow login');
+        }
+        client = { apiUrl: client.apiUrl, token: hit.token, source: 'folder', organizationId: hit.organizationId };
+        card = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}`);
+        (0, ui_1.note)((0, ui_1.dim)(`  The project belongs to "${hit.name ?? hit.organizationId}", not to the active organization`));
+    }
     const dir = existing ? root : process.cwd();
     (0, config_1.writeConfig)(dir, {
         ...(existing ?? {}),
@@ -113,6 +137,8 @@ async function link(args) {
         build: existing?.build ?? { command: 'npm run build', dir: 'dist' },
     });
     (0, config_1.ignoreStateInGit)(dir);
+    if (client.organizationId)
+        (0, config_1.writeState)(dir, { organizationId: client.organizationId });
     // A fresh clone has no .env: recreate it, never overwrite an existing one.
     if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(dir, '.env')) && card.project_token) {
         write(dir, '.env', (0, template_1.envFile)(card.project_token, client.apiUrl, card.functions));

package/dist/commands/sources.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.latestRevision = latestRevision;
 exports.pushSources = pushSources;
-exports.push = push;
 exports.pull = pull;
 exports.status = status;
 const node_fs_1 = require("node:fs");
@@ -69,7 +68,7 @@ async function confirmForce(client, projectId, server, local) {
     if (!confirmed)
         throw new errors_1.CliError('Cancelled');
 }
-/** Used by push and by the first step of deploy. */
+/** The first step of deploy: sources go up as a revision before the build. */
 async function pushSources(root, config, client, options) {
     const tree = prepareTree(root, config);
     const state = (0, config_1.readState)(root);
@@ -79,7 +78,11 @@ async function pushSources(root, config, client, options) {
     // a mismatch must not overwrite silently.
     if (server && state.revision === undefined && !options.force) {
         if (server.tree_hash === tree.hash) {
-            (0, config_1.writeState)(root, { revision: server.revision, treeHash: server.tree_hash });
+            (0, config_1.writeState)(root, {
+                revision: server.revision,
+                treeHash: server.tree_hash,
+                organizationId: client.organizationId ?? undefined,
+            });
             (0, ui_1.ok)(`Already in sync, revision ${server.revision}`);
             return { revision: server.revision, status: 'unchanged' };
         }
@@ -94,7 +97,11 @@ async function pushSources(root, config, client, options) {
     if (options.force)
         headers['X-Force'] = 'true';
     const result = await (0, api_1.apiUpload)(client, `/api/v1/projects/${config.projectId}/push`, tree.archive, headers);
-    (0, config_1.writeState)(root, { revision: result.revision, treeHash: result.tree_hash });
+    (0, config_1.writeState)(root, {
+        revision: result.revision,
+        treeHash: result.tree_hash,
+        organizationId: client.organizationId ?? undefined,
+    });
     if (result.status === 'unchanged') {
         (0, ui_1.ok)(`No changes, revision ${result.revision}`);
     }
@@ -103,11 +110,6 @@ async function pushSources(root, config, client, options) {
     }
     return { revision: result.revision, status: result.status };
 }
-async function push(args) {
-    const { root, config } = (0, config_1.requireProject)();
-    const client = (0, session_1.connect)(config);
-    await pushSources(root, config, client, { force: (0, args_1.flagBool)(args, 'force') });
-}
 function hasContent(dir) {
     if (!(0, node_fs_1.existsSync)(dir))
         return false;
@@ -117,7 +119,7 @@ async function pull(args) {
     const { root, config } = (0, config_1.requireProject)();
     const into = (0, args_1.flagString)(args, 'into');
     const target = into ? (0, node_path_1.resolve)(into) : root;
-    const client = (0, session_1.connect)(config);
+    const client = await (0, session_1.connectProject)(root, config);
     const revision = (0, args_1.flagNumber)(args, 'revision');
     const query = revision !== undefined ? `?revision=${revision}` : '';
     const info = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/pull${query}`);
@@ -139,13 +141,17 @@ async function pull(args) {
     }
     // Only the working folder tracks revisions; a side copy (--into) must not reset them.
     if (!into) {
-        (0, config_1.writeState)(root, { revision: info.revision, treeHash: info.tree_hash });
+        (0, config_1.writeState)(root, {
+            revision: info.revision,
+            treeHash: info.tree_hash,
+            organizationId: client.organizationId ?? undefined,
+        });
     }
     (0, ui_1.ok)(`Revision ${info.revision}: ${entries.length} files in ${target}`);
 }
 async function status() {
     const { root, config } = (0, config_1.requireProject)();
-    const client = (0, session_1.connect)(config);
+    const client = await (0, session_1.connectProject)(root, config);
     const tree = prepareTree(root, config);
     const state = (0, config_1.readState)(root);
     const [card, server] = await Promise.all([
@@ -157,7 +163,7 @@ async function status() {
     (0, ui_1.out)(`Local:      ${tree.files.length} files, ${(0, ui_1.formatBytes)(tree.archive.length)} archived`);
     if (!server) {
         (0, ui_1.out)('On the server: no sources yet');
-        (0, ui_1.note)((0, ui_1.dim)('  Send them: xflow push'));
+        (0, ui_1.note)((0, ui_1.dim)('  Send and build them: xflow deploy'));
     }
     else {
         (0, ui_1.out)(`On the server: revision ${server.revision}, ${server.file_count} files, ${(0, ui_1.formatAge)(server.created_at)}`);
@@ -170,7 +176,7 @@ async function status() {
         }
         else {
             (0, ui_1.out)(`State: ${(0, ui_1.bold)('local changes')}`);
-            (0, ui_1.note)((0, ui_1.dim)('  Send them: xflow push'));
+            (0, ui_1.note)((0, ui_1.dim)('  Send and build them: xflow deploy'));
         }
     }
     (0, ui_1.out)('');

package/dist/config.js

@@ -4,6 +4,7 @@ exports.ConfigError = exports.CONFIG_FILE = void 0;
 exports.findProjectRoot = findProjectRoot;
 exports.readConfig = readConfig;
 exports.writeConfig = writeConfig;
+exports.localConfig = localConfig;
 exports.requireProject = requireProject;
 exports.apiUrlFor = apiUrlFor;
 exports.readState = readState;
@@ -47,6 +48,18 @@ function readConfig(root) {
 function writeConfig(root, config) {
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, exports.CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
 }
+/** The config of the folder we are in, when there is one and it parses. */
+function localConfig() {
+    const root = findProjectRoot();
+    if (!root)
+        return undefined;
+    try {
+        return readConfig(root);
+    }
+    catch {
+        return undefined;
+    }
+}
 function requireProject() {
     const root = findProjectRoot();
     if (!root) {
@@ -75,9 +88,15 @@ function readState(root) {
         return {};
     }
 }
-function writeState(root, state) {
+/** Merge, never replace: callers write their own fields, the rest survives. */
+function writeState(root, patch) {
     const dir = (0, node_path_1.join)(root, STATE_DIR);
     (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const state = { ...readState(root) };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value !== undefined)
+            state[key] = value;
+    }
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, 'state.json'), `${JSON.stringify(state, null, 2)}\n`, 'utf-8');
 }
 /** Keep .xflow/ out of git. */

package/dist/credentials.js

@@ -1,9 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.saveCredential = saveCredential;
-exports.forgetCredential = forgetCredential;
-exports.resolveToken = resolveToken;
-exports.readCredential = readCredential;
+exports.reconcile = reconcile;
+exports.listOrgs = listOrgs;
+exports.saveOrgCredential = saveOrgCredential;
+exports.rememberOrgName = rememberOrgName;
+exports.setActiveOrg = setActiveOrg;
+exports.forgetOrg = forgetOrg;
+exports.forgetAllOrgs = forgetAllOrgs;
+exports.anyMultipleOrgs = anyMultipleOrgs;
+exports.pickKey = pickKey;
+exports.storedKeyInputs = storedKeyInputs;
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -38,28 +44,208 @@ function writeStore(store) {
         // Windows has no POSIX modes.
     }
 }
-function saveCredential(apiUrl, credential) {
+function isLegacy(value) {
+    return !!value && typeof value.token === 'string';
+}
+/** The mirror for older CLIs: the key of the active organization, or nothing. */
+function syncLegacy(store, apiUrl) {
+    const address = store.orgs?.[apiUrl];
+    if (!address)
+        return;
+    const active = address.active ? address.keys[address.active] : undefined;
+    if (active && address.active) {
+        store[apiUrl] = { token: active.token, organizationId: address.active, savedAt: active.savedAt };
+        address.mirror = address.active;
+    }
+    else {
+        delete store[apiUrl];
+        address.mirror = null;
+    }
+}
+/**
+ * Fold writes made by an older CLI back into the map. Its login rewrites only
+ * the mirror record, its logout deletes only it; both are treated as what the
+ * person meant: "sign in to this organization" and "forget the key I am using".
+ * Returns true when the store changed and has to be written back.
+ */
+function reconcile(store, apiUrl) {
+    const legacy = store[apiUrl];
+    let address = store.orgs?.[apiUrl];
+    let changed = false;
+    if (isLegacy(legacy) && legacy.organizationId) {
+        const orgs = address ?? { active: null, keys: {} };
+        const known = orgs.keys[legacy.organizationId];
+        if (!known || known.token !== legacy.token || orgs.active !== legacy.organizationId) {
+            orgs.keys[legacy.organizationId] = { ...known, token: legacy.token, savedAt: legacy.savedAt };
+            orgs.active = legacy.organizationId;
+            store.orgs = store.orgs ?? {};
+            store.orgs[apiUrl] = orgs;
+            address = orgs;
+            changed = true;
+        }
+    }
+    if (!isLegacy(legacy) && address?.active && address.keys[address.active]) {
+        if (address.mirror === address.active) {
+            // The mirror we wrote for this key is gone: an older CLI logged out.
+            delete address.keys[address.active];
+            address.active = null;
+        }
+        // Otherwise no mirror was ever written for this key (a hand-made or
+        // restored file): deleting it would lose a key nobody asked to forget.
+        // Either way the store changed: the mirror has to be rebuilt.
+        changed = true;
+    }
+    // The pointer must land on a stored key, or on nothing.
+    if (address) {
+        const ids = Object.keys(address.keys);
+        const active = address.active && address.keys[address.active] ? address.active : (ids[0] ?? null);
+        if (address.active !== active) {
+            address.active = active;
+            changed = true;
+        }
+    }
+    if (changed)
+        syncLegacy(store, apiUrl);
+    return changed;
+}
+/** Read the store with the drift of older CLIs healed, persisting the healing. */
+function load(apiUrl) {
     const store = readStore();
-    store[apiUrl] = { ...credential, savedAt: new Date().toISOString() };
+    if (reconcile(store, apiUrl))
+        commit(store, apiUrl);
+    return store;
+}
+function commit(store, apiUrl) {
+    syncLegacy(store, apiUrl);
+    const address = store.orgs?.[apiUrl];
+    if (address && Object.keys(address.keys).length === 0) {
+        delete store.orgs?.[apiUrl];
+        if (store.orgs && Object.keys(store.orgs).length === 0)
+            delete store.orgs;
+    }
     writeStore(store);
 }
-function forgetCredential(apiUrl) {
+/** Organizations with a stored key for the address, the active one first. */
+function listOrgs(apiUrl) {
+    const address = load(apiUrl).orgs?.[apiUrl];
+    if (!address)
+        return [];
+    return Object.entries(address.keys)
+        .map(([organizationId, key]) => ({
+        organizationId,
+        name: key.name ?? null,
+        token: key.token,
+        active: organizationId === address.active,
+    }))
+        .sort((a, b) => Number(b.active) - Number(a.active));
+}
+/** Store the key and make its organization the active one. */
+function saveOrgCredential(apiUrl, organizationId, token, name) {
+    const store = readStore();
+    reconcile(store, apiUrl);
+    const orgs = store.orgs?.[apiUrl] ?? { active: null, keys: {} };
+    const known = orgs.keys[organizationId];
+    orgs.keys[organizationId] = {
+        token,
+        name: name ?? known?.name ?? null,
+        savedAt: new Date().toISOString(),
+    };
+    orgs.active = organizationId;
+    store.orgs = store.orgs ?? {};
+    store.orgs[apiUrl] = orgs;
+    commit(store, apiUrl);
+}
+/** Cache the display name; a stale one is refreshed by any login or whoami. */
+function rememberOrgName(apiUrl, organizationId, name) {
     const store = readStore();
-    if (!store[apiUrl])
+    reconcile(store, apiUrl);
+    const entry = store.orgs?.[apiUrl]?.keys[organizationId];
+    if (!entry || entry.name === name)
+        return;
+    entry.name = name;
+    commit(store, apiUrl);
+}
+function setActiveOrg(apiUrl, organizationId) {
+    const store = readStore();
+    reconcile(store, apiUrl);
+    const orgs = store.orgs?.[apiUrl];
+    if (!orgs?.keys[organizationId])
+        return false;
+    if (orgs.active !== organizationId) {
+        orgs.active = organizationId;
+        commit(store, apiUrl);
+    }
+    return true;
+}
+/** Forget one organization; the pointer moves to any remaining one. */
+function forgetOrg(apiUrl, organizationId) {
+    const store = readStore();
+    reconcile(store, apiUrl);
+    const orgs = store.orgs?.[apiUrl];
+    if (!orgs?.keys[organizationId])
+        return { removed: false, nextActive: null };
+    delete orgs.keys[organizationId];
+    if (orgs.active === organizationId)
+        orgs.active = Object.keys(orgs.keys)[0] ?? null;
+    commit(store, apiUrl);
+    const next = orgs.active ? orgs.keys[orgs.active] : undefined;
+    return {
+        removed: true,
+        nextActive: next && orgs.active
+            ? { organizationId: orgs.active, name: next.name ?? null, token: next.token, active: true }
+            : null,
+    };
+}
+/** Forget every key of the address; other addresses are untouched. */
+function forgetAllOrgs(apiUrl) {
+    const store = readStore();
+    reconcile(store, apiUrl);
+    const had = !!store.orgs?.[apiUrl] || isLegacy(store[apiUrl]);
+    if (!had)
         return false;
+    if (store.orgs) {
+        delete store.orgs[apiUrl];
+        if (Object.keys(store.orgs).length === 0)
+            delete store.orgs;
+    }
     delete store[apiUrl];
     writeStore(store);
     return true;
 }
-/** XFLOW_TOKEN wins over the store; the caller decides whether env is allowed for this address. */
-function resolveToken(apiUrl, allowEnv = true) {
-    if (allowEnv) {
-        const fromEnv = process.env.XFLOW_TOKEN?.trim();
-        if (fromEnv)
-            return fromEnv;
+/** True when any address holds keys of more than one organization. */
+function anyMultipleOrgs() {
+    const store = readStore();
+    return Object.values(store.orgs ?? {}).some((address) => Object.keys(address.keys).length > 1);
+}
+/**
+ * One rule for the whole CLI: XFLOW_TOKEN (default address only) beats the
+ * folder's organization, which beats the active one. A folder bound to an
+ * organization without a stored key is an error, not a fallback: the command
+ * would silently run against a different organization.
+ */
+function pickKey(inputs) {
+    if (inputs.envAllowed && inputs.env)
+        return { token: inputs.env, source: 'env', organizationId: null };
+    if (inputs.folderOrg) {
+        const key = inputs.orgs?.keys[inputs.folderOrg];
+        if (key)
+            return { token: key.token, source: 'folder', organizationId: inputs.folderOrg };
+        return { missing: 'folder-key', organizationId: inputs.folderOrg };
     }
-    return readStore()[apiUrl]?.token ?? null;
+    const activeId = inputs.orgs?.active;
+    const active = activeId ? inputs.orgs?.keys[activeId] : undefined;
+    if (active && activeId)
+        return { token: active.token, source: 'active', organizationId: activeId };
+    if (inputs.legacyToken)
+        return { token: inputs.legacyToken, source: 'active', organizationId: null };
+    return null;
 }
-function readCredential(apiUrl) {
-    return readStore()[apiUrl] ?? null;
+/** The store-backed half of pickKey's inputs; the caller adds env and the folder binding. */
+function storedKeyInputs(apiUrl) {
+    const store = load(apiUrl);
+    const legacy = store[apiUrl];
+    return {
+        orgs: store.orgs?.[apiUrl] ?? null,
+        legacyToken: isLegacy(legacy) ? legacy.token : null,
+    };
 }

package/dist/help.js

@@ -19,9 +19,8 @@ ${(0, ui_1.bold)('Getting started')}
   xflow skills                    pick the agents that get the platform instructions
   xflow mcp install               give the agent platform access without a terminal
 
-${(0, ui_1.bold)('Code')}
+${(0, ui_1.bold)('Sources')}
   xflow status                    what is on the server and how the local copy differs
-  xflow push [--force]            send the sources as a new revision
   xflow pull [--into dir] [--revision N]
                                   fetch the sources (the latest revision by default)
 
@@ -60,8 +59,10 @@ ${(0, ui_1.bold)('Reference')}
   xflow logs [--limit N]          browser errors from the released application
   xflow projects list             projects of the organization
   xflow projects get [id]         project card
+  xflow org                       organizations with a stored key, the active one marked
+  xflow org switch <name|id>      make another organization the active one
   xflow whoami                    whose key this is and what it can do
-  xflow logout                    forget the key
+  xflow logout [--all]            forget the key of the active organization (--all: every one)
   xflow update                    update the CLI itself, and the skill that ships with it
 
 ${(0, ui_1.bold)('Environment')}
@@ -71,6 +72,35 @@ ${(0, ui_1.bold)('Environment')}
 More about one command: xflow help <command>`);
 }
 const TOPICS = {
+    org: `${(0, ui_1.bold)('xflow org')}: several organizations, one terminal
+
+One key per organization: every ${(0, ui_1.bold)('xflow login')} stores the key of the organization
+chosen in the browser next to the ones already stored, it does not replace them.
+Which key a command then uses, in order:
+
+  1. XFLOW_TOKEN, when set (and only for the default platform address)
+  2. the organization this folder is bound to (${(0, ui_1.bold)('.xflow/state.json')}, written by
+     init, link and the first successful deploy or pull)
+  3. the active organization
+
+  xflow org                      the stored organizations, the active one marked
+  xflow org switch <name|id>     make another one active, no browser involved
+  xflow logout                   forget the key of the active organization
+  xflow logout --all             forget every key of this platform address
+
+The switch is local: it changes which stored key is used and nothing happens on
+the platform. A folder bound to an organization is not affected, its commands
+stay in its own organization: two projects of two organizations in two terminals
+work without switching anything.
+
+Outside a project folder the switch also rewrites the key in the agent config
+(see ${(0, ui_1.bold)('xflow mcp')}) when an xflow entry already exists there; a running agent
+session picks the new key up only after a restart.
+
+A project id is unique across the whole platform, so "project not found" under
+the wrong organization can never touch somebody else's project. When that error
+names a project you know exists, the key is simply from another organization:
+check ${(0, ui_1.bold)('xflow org')}.`,
     update: `${(0, ui_1.bold)('xflow update')}: bring the CLI up to date
 
 Installs the published version and, if anything changed, rewrites the platform
@@ -291,20 +321,6 @@ Plus a few pointer lines in ${(0, ui_1.bold)('AGENTS.md')}. A skill is picked up
 description matches the task, and "add a customers table" will not trigger it. AGENTS.md
 is always read by the agent, which is why the pointer is appended there, at the end of
 the file and once. ${(0, ui_1.bold)('CLAUDE.md')} is left alone: Claude Code reads .claude/skills anyway.`,
-    push: `${(0, ui_1.bold)('xflow push')}: send the sources
-
-The whole working copy goes up at once, as one revision. What is not sent:
-node_modules, .git, dist, build, .next, any .env, plus everything listed in
-.xflowignore and in the ignore field of xflow.json.
-
-If the server holds a revision newer than the one you worked from, the push is
-rejected. That means somebody pushed before you: fetch their changes alongside
-(${(0, ui_1.bold)('xflow pull --into ./server-copy')}), merge them in git on your side, and retry.
-
---force overwrites the server revision. Before that the CLI shows whose work you are
-about to destroy and asks for confirmation by typing the project name. In a
-non-interactive run (CI, an agent) there is no way to confirm: a version conflict has
-to fail the build rather than silently destroy somebody else's work.`,
     pull: `${(0, ui_1.bold)('xflow pull')}: fetch the sources
 
 By default it fetches the latest revision into the project folder and refuses to write
@@ -323,6 +339,18 @@ by default).
   --force            allow overwriting the server revision while sending
   --allow-removals   agree in advance to remove the functions gone from the sources
 
+The whole working copy goes up at once, as one revision. What is not sent: node_modules,
+.git, dist, build, .next, any .env, plus everything listed in .xflowignore and in the
+ignore field of xflow.json.
+
+If the server holds a revision newer than the one you worked from, the sources are
+rejected and the build does not start. That means somebody deployed before you: fetch
+their changes alongside (${(0, ui_1.bold)('xflow pull --into ./server-copy')}), merge them in git on
+your side, and retry. ${(0, ui_1.bold)('--force')} overwrites the server revision, and before that the
+CLI shows whose work you are about to destroy and asks for confirmation by typing the
+project name. In a non-interactive run (CI, an agent) there is no way to confirm: a
+version conflict has to fail the build rather than silently destroy somebody else's work.
+
 The platform builds, in a clean sandbox on one Node version for everybody, so "it
 worked on my machine" no longer depends on your machine. Before the build the project
 is checked against the template: mismatches are printed as a list and the build does

package/dist/session.js

@@ -2,21 +2,84 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.connect = connect;
 exports.anonymous = anonymous;
+exports.findProjectOrg = findProjectOrg;
+exports.connectProject = connectProject;
+const api_1 = require("./api");
 const config_1 = require("./config");
 const credentials_1 = require("./credentials");
 const errors_1 = require("./errors");
+const ui_1 = require("./ui");
 /** Platform connection: address plus key. */
 function connect(config) {
     const apiUrl = (0, config_1.apiUrlFor)(config);
-    // XFLOW_TOKEN never follows an address taken from the repo's xflow.json:
-    // a cloned config must not be able to redirect the key elsewhere.
-    const token = (0, credentials_1.resolveToken)(apiUrl, apiUrl === (0, config_1.apiUrlFor)());
-    if (!token) {
+    const root = (0, config_1.findProjectRoot)();
+    const picked = (0, credentials_1.pickKey)({
+        env: process.env.XFLOW_TOKEN?.trim() || null,
+        // XFLOW_TOKEN never follows an address taken from the repo's xflow.json:
+        // a cloned config must not be able to redirect the key elsewhere.
+        envAllowed: apiUrl === (0, config_1.apiUrlFor)(),
+        folderOrg: root ? ((0, config_1.readState)(root).organizationId ?? null) : null,
+        ...(0, credentials_1.storedKeyInputs)(apiUrl),
+    });
+    if (!picked) {
         throw new errors_1.CliError(`No access key for ${apiUrl}`, 'Sign in: xflow login. In CI pass the key in the XFLOW_TOKEN variable');
     }
-    return { apiUrl, token };
+    if ('missing' in picked) {
+        throw new errors_1.CliError(`This folder is bound to the organization ${picked.organizationId}, and there is no stored key for it`, 'Sign in to that organization: xflow login. The stored ones: xflow org');
+    }
+    return { apiUrl, token: picked.token, source: picked.source, organizationId: picked.organizationId };
 }
 /** Sign-in only. */
 function anonymous(config) {
     return { apiUrl: (0, config_1.apiUrlFor)(config), token: '' };
 }
+/**
+ * Which signed-in organization serves the project. Project ids are unique
+ * across the platform, so a 404 means "not this one" and exactly one
+ * organization can answer. A dead key must not end the search: the answer may
+ * sit behind the next one.
+ */
+async function findProjectOrg(apiUrl, projectId) {
+    const dead = [];
+    for (const candidate of (0, credentials_1.listOrgs)(apiUrl)) {
+        try {
+            await (0, api_1.apiJson)({ apiUrl, token: candidate.token }, `/api/v1/projects/${projectId}`);
+            return { hit: candidate, dead };
+        }
+        catch (e) {
+            if (e instanceof api_1.ApiError && (e.status === 401 || e.status === 403)) {
+                dead.push(candidate);
+                continue;
+            }
+            if (e instanceof api_1.ApiError && e.status === 404)
+                continue;
+            throw e;
+        }
+    }
+    return { hit: null, dead };
+}
+/**
+ * Connection for project commands. A folder not yet bound to an organization
+ * gets probed once: the organization that serves the project is found and
+ * written into .xflow/state.json, so every later command resolves the key
+ * synchronously. With one stored key there is nothing to probe.
+ */
+async function connectProject(root, config) {
+    const session = connect(config);
+    if (session.source !== 'active' || session.organizationId === null)
+        return session;
+    const orgs = (0, credentials_1.listOrgs)(session.apiUrl);
+    if (orgs.length <= 1)
+        return session;
+    const { hit, dead } = await findProjectOrg(session.apiUrl, config.projectId);
+    if (!hit) {
+        throw new errors_1.CliError(`No signed-in organization holds the project ${config.projectId}`, dead.length > 0
+            ? `The key of ${dead.map((d) => d.name ?? d.organizationId).join(', ')} is not working (sign in again: xflow login); the project may live there`
+            : 'Check projectId in xflow.json, or sign in to the organization that owns it: xflow login');
+    }
+    (0, config_1.writeState)(root, { organizationId: hit.organizationId });
+    if (hit.organizationId !== session.organizationId) {
+        (0, ui_1.note)((0, ui_1.dim)(`  The project belongs to "${hit.name ?? hit.organizationId}", not to the active organization: the folder is bound to it`));
+    }
+    return { apiUrl: session.apiUrl, token: hit.token, source: 'folder', organizationId: hit.organizationId };
+}

package/dist/version.js

@@ -2,6 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_API_URL = exports.CLI_VERSION = void 0;
 /** Keep in sync with cli/package.json. */
-exports.CLI_VERSION = '0.6.6';
+exports.CLI_VERSION = '0.8.0';
 /** Overridden by XFLOW_API_URL or the `api` field in xflow.json. */
 exports.DEFAULT_API_URL = 'https://app.getxflow.com';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getxflow/cli",
-  "version": "0.6.6",
+  "version": "0.8.0",
   "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
   "license": "UNLICENSED",
   "engines": {

package/skills/xflow/SKILL.md

@@ -312,9 +312,13 @@ const db = new Client({ connectionString: process.env.DATABASE_URL })
 
 The platform passes `DATABASE_URL` only to functions that mention it, and sets the project
 schema on every connection, so plain table names (`select * from tasks`) hit your project.
-You never write that variable yourself: `xflow env set DATABASE_URL=...` is refused. The same
-goes for every name starting with `XFLOW`: the platform fills those in itself, and your value
-under one of them would shadow the real one.
+You never write that variable yourself: `xflow env set DATABASE_URL=...` is refused, and so is
+`xflow env rm DATABASE_URL`. The same goes for every name starting with `XFLOW`: the platform
+fills those in itself, and your value under one of them would shadow the real one.
+
+`env` commands reach only what this project can see: variables shared across the organization
+and the ones bound to this project. A variable bound to a different project is invisible here,
+so `env rm` reports it as missing even though names are unique within the organization.
 
 The platform keeps no database history and no backups. Anything that destroys data
 (`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE FROM` without a condition) is refused
@@ -357,12 +361,17 @@ const link = await fetch(`${process.env.XFLOW_API_URL}/api/storage/project/uploa
 ```
 
 `confirm` takes the same fields plus the returned `s3Key` and answers with the file and its
-public address; `delete` takes the file `url`. Never pipe the bytes through the function itself.
+address; `delete` takes that same `url`. Never pipe the bytes through the function itself.
 
 There is no endpoint that lists the files back, so the address that `confirm` returns is the
 only copy you get: write it into a table of your own in the same call, and the application
 reads its files from there.
 
+That address never expires and is safe to store, but it is not a public link. It opens only
+for a visitor who is signed in and has access to this project, the same rule that guards the
+application itself, so it works on your pages and does nothing in an email or on a page
+anyone can open.
+
 Four things bite an upload that otherwise looks right, and none of them is obvious from the
 answers you get:
 
@@ -393,12 +402,30 @@ key that reached a visitor lets them delete every file of the project.
 ## Syncing code
 
 `xflow status` shows how the local copy differs from the server revision.
-`xflow push` sends sources, `xflow pull` fetches them.
-
-If a push is rejected, the server revision is newer, meaning someone pushed first.
-Fetch their work next to yours (`xflow pull --into ./server-copy`), merge it locally,
-then push again. `--force` destroys their work: a last resort, not a way around the
-error.
+`xflow deploy` sends sources, `xflow pull` fetches them.
+
+If a deploy is rejected before the build starts, the server revision is newer, meaning
+someone deployed first. Fetch their work next to yours (`xflow pull --into ./server-copy`),
+merge it locally, then deploy again. `--force` destroys their work: a last resort, not a
+way around the error.
+
+## Organizations and keys
+
+A key belongs to one organization, and `xflow login` stores it next to the ones already
+stored instead of replacing them. Which key a command uses, in order: `XFLOW_TOKEN` when
+set (default platform address only), then the organization the project folder is bound
+to (`.xflow/state.json`, written by init, link and the first successful deploy or pull),
+then the active organization. `xflow org` lists the stored organizations with the active
+one marked, `xflow org switch <name|id>` makes another one active without a browser, and
+`xflow whoami` names the organization behind the current key.
+
+Inside a project folder there is nothing to switch: commands follow the folder's own
+organization whatever the active one is, which is what lets two projects of two
+organizations work side by side. Project ids are unique across the platform, so a key of
+the wrong organization can never touch another organization's project: the command fails
+with "not found" instead. When that error names a project you know exists, check
+`xflow org`; signing in to a missing organization is `xflow login`, and that needs a
+person with a browser.
 
 ## Direct access without the terminal
 
@@ -408,8 +435,8 @@ read-only queries, migrations, function logs and invocations, schedules, environ
 variables, versions, publish and rollback. They answer with aggregates and say explicitly
 when a result is truncated, which parsing terminal output does not.
 
-Anything that depends on the working copy stays in the CLI: sending sources (`xflow push`),
-building and shipping the functions (`xflow deploy`), creating a project (`xflow init`). The
+Anything that depends on the working copy stays in the CLI: sending sources, building and
+shipping the functions (`xflow deploy`), creating a project (`xflow init`). The
 tools cannot see the folder you are working in, so a build started from there would release
 whatever revision the server happens to hold, not what you have on disk. Pulling a repository
 through tool calls also burns the user's tokens for nothing.
@@ -418,7 +445,7 @@ through tool calls also burns the user's tokens for nothing.
 
 - Edit `xflow.json` by hand: the CLI writes it.
 - Commit `.env`: it holds the project token.
-- Push with `--force` without checking `xflow status` first.
+- Deploy with `--force` without checking `xflow status` first.
 - Invent platform commands: what is not in `xflow help` does not exist.
 
 ## App design