@seliseblocks/cli-os 0.1.5 → 0.2.1

package/AI_USAGE_GUIDE.md

@@ -128,10 +128,10 @@ Then run with explicit flags so no prompt is reached:
 blocks new web <appName> --x-blocks-key <projectTenantId> --app-domain <appDomainOrUrl> --client-id <publicOidcClientId>
 ```
 
-`new web` also accepts `--blocks-api-url <url>` and `--oidc-url <url>`, same as `sdk client`
-below. `--blocks-api-url` defaults to `https://api.seliseblocks.com` if omitted - pass a
-different Data/IAM/Localization/OS gateway URL explicitly only if your project uses a
-non-default one. `--oidc-url` defaults to `https://iam.seliseblocks.com`.
+`new web` also accepts `--blocks-api-url <url>` and `--oidc-url <url>`, same as `sdk client`
+below. When `--blocks-api-url` is omitted, the scaffold derives it from the app domain as
+`https://blocksapi.<registrable-domain>`; for example `https://dqrsf.slsblx.com` becomes
+`https://blocksapi.slsblx.com`. Pass `--blocks-api-url` only when targeting a non-default Blocks gateway. `--oidc-url` defaults to `https://iam.seliseblocks.com`.
 
 Validate the scaffold:
 
@@ -160,10 +160,10 @@ The generated cert script uses the `selfsigned` Node dependency, so it works fro
 `sdk client` answers "I want to use the Blocks SDK - show me the client." It resolves this project's `@seliseblocks/client` config (same values `new web` scaffolds an app with) and prints a ready-to-paste `createBlocksClient(...)` snippet - **it never writes a file or mutates anything**. To scaffold a full app instead, use `new web` above.
 
 ```bash
-blocks sdk client --x-blocks-key <projectTenantId> --app-domain <appDomainOrUrl> --client-id <publicOidcClientId> --blocks-api-url https://api.seliseblocks.com
+blocks sdk client --x-blocks-key <projectTenantId> --app-domain <appDomainOrUrl> --client-id <publicOidcClientId> --blocks-api-url https://api.seliseblocks.com
 ```
 
-As with `new web`, `--blocks-api-url` already defaults to `https://api.seliseblocks.com`; only pass it explicitly if your project uses a different gateway URL. Passing both `--app-domain` and `--client-id` skips the project lookup entirely, so it needs no CLI login at all - useful for a quick, non-interactive check. Omit either one and it resolves from the selected project instead (auto-picks when there's exactly one match, otherwise lists the options and asks you to pass the flag explicitly - it does not prompt or create anything, since this command is read-only). Use `--json` for the resolved values instead of the snippet.
+Unlike `new web`, `sdk client` keeps `--blocks-api-url` defaulted to `https://api.seliseblocks.com`; only pass it explicitly if your project uses a different gateway URL. Passing both `--app-domain` and `--client-id` skips the project lookup entirely, so it needs no CLI login at all - useful for a quick, non-interactive check. Omit either one and it resolves from the selected project instead (auto-picks when there's exactly one match, otherwise lists the options and asks you to pass the flag explicitly - it does not prompt or create anything, since this command is read-only). Use `--json` for the resolved values instead of the snippet.
 
 ## Skills
 
@@ -181,9 +181,9 @@ Every other command below is project-scoped: it requires a project already selec
 
 Command families (run `blocks --help` for the full flag reference on each):
 
-- `iam users *`, `iam email available` - list/get/create/update/activate/deactivate, access grant/revoke, existence and email-availability checks.
-- `iam roles *` - list/get/create/update, assign-permissions, assignable.
-- `iam permissions *` - list/get/create/update, by-severity.
+- `iam users *`, `iam email available` - list/get/create/update/activate/deactivate, access grant/revoke, existence and email-availability checks.
+- `iam roles *` - list/get/create/update, assign-permissions, assignable. `assign-permissions` accepts permission resource strings and resolves them to itemIds before sending IAM's id-based mutation.
+- `iam permissions *` - list/get/create/update, by-severity.
 - `iam resources *` - resource groups and feature flags (read-only).
 - `iam organizations *` - list/get/create/update, `my`, and organization config get/save.
 - `iam signup-settings *` - get/save tenant signup policy.

package/README.md

@@ -10,7 +10,7 @@ CLI for SELISE Blocks Cloud.
 Install the npm package where you want to operate the CLI:
 
 ```bash
-npm install -g @seliseblocks/cli-os
+npm install -g @seliseblocks/cli-os@latest
 blocks --version
 ```
 
@@ -95,9 +95,9 @@ Global options available on every command:
 | `blocks release status <buildId> [--json]` | Read Release build status by build id. Read-only. |
 | `blocks release builds list [repoId] [--repo-id <repoId>] [--json]` | List Release build details for a repository. When `repoId` is omitted, resolves it from the selected project's linked repo assets - auto-picked if there's exactly one, otherwise you're prompted to choose. Read-only. |
 | `blocks release builds get <buildId> [--json]` | Alias for `release status`. Read-only. |
-| `blocks new web <name> [--app-domain <domain>] [--client-id <oidcClientId>] [--x-blocks-key <tenantId>] [--blocks-api-url <url>] [--oidc-url <url>]` | Create a Vite React starter app that talks to Blocks exclusively through `@seliseblocks/client` (a single `createBlocksClient()` instance) using the SDK hosted IdP flow: `blocksClient.auth.idp.redirectToProvider()` on login click and `blocksClient.auth.idp.callback()` on `/login/callback`. Includes route guards, auto-refresh through `auth.oidc.refreshToken()`, live `auth`/`iam`/`data`/`localization` SDK examples, environment config, and safe `.gitignore` defaults. Uses the selected project (see `use`) unless `--x-blocks-key` overrides it. `--app-domain` and `--client-id` are resolved from the project record when omitted: the domain auto-picks if the project has exactly one, otherwise you're prompted to choose; the OIDC client is picked from the project's existing clients, or you can create a minimal one (display name + redirect URI) on the spot, or skip and register one later from the portal or `auth oidc-clients save`. `--blocks-api-url` defaults to `https://api.seliseblocks.com` if omitted - pass a different Data/IAM/Localization/OS gateway URL explicitly only if your project uses a non-default one. `--oidc-url` defaults to `https://iam.seliseblocks.com`. |
+| `blocks new web <name> [--app-domain <domain>] [--client-id <oidcClientId>] [--x-blocks-key <tenantId>] [--blocks-api-url <url>] [--oidc-url <url>]` | Create a Vite React starter app that talks to Blocks exclusively through `@seliseblocks/client` (a single `createBlocksClient()` instance) using the SDK hosted IdP flow: `blocksClient.auth.idp.redirectToProvider()` on login click and `blocksClient.auth.idp.callback()` on `/login/callback`. Includes route guards, auto-refresh through `auth.oidc.refreshToken()`, live `auth`/`iam`/`data`/`localization` SDK examples, environment config, and safe `.gitignore` defaults. Uses the selected project (see `use`) unless `--x-blocks-key` overrides it. `--app-domain` and `--client-id` are resolved from the project record when omitted: the domain auto-picks if the project has exactly one, otherwise you're prompted to choose; the OIDC client is picked from the project's existing clients, or you can create a minimal one (display name + redirect URI) on the spot, or skip and register one later from the portal or `auth oidc-clients save`. When `--blocks-api-url` is omitted, `new web` derives it from the app domain as `https://blocksapi.<registrable-domain>`; for example `https://dqrsf.slsblx.com` becomes `https://blocksapi.slsblx.com`. Pass a different Data/IAM/Localization/OS gateway URL explicitly only if your project uses a non-default one. `--oidc-url` defaults to `https://iam.seliseblocks.com`. |
 | `blocks skill list [--json]` / `skill show <name> [--json]` / `skill add <name> [--dir <path>]` | Local-only, no cloud calls: list/print the bundled `blocks-skills/*/SKILL.md` agent context docs, or copy a skill's entire directory (`SKILL.md` plus any supporting files) into `<dir>/<name>/` (default `./blocks-skills`) for use in a project outside this monorepo. `list`'s output and `show`/`add`'s "unknown skill" error both point at the full public skill catalog in case the bundled set is out of date. |
-| `blocks sdk client [--app-domain <domain>] [--client-id <oidcClientId>] [--x-blocks-key <tenantId>] [--blocks-api-url <url>] [--oidc-url <url>] [--json]` | Read-only: resolves this project's `@seliseblocks/client` config (same values `new web` scaffolds with) and prints a ready-to-paste `createBlocksClient(...)` snippet. Passing both `--app-domain` and `--client-id` skips the project lookup entirely (no login required). Writes nothing - use `new web` to scaffold a full app. |
+| `blocks sdk client [--app-domain <domain>] [--client-id <oidcClientId>] [--x-blocks-key <tenantId>] [--blocks-api-url <url>] [--oidc-url <url>] [--json]` | Read-only: resolves this project's `@seliseblocks/client` config and prints a ready-to-paste `createBlocksClient(...)` snippet. Unlike `new web`, the API URL defaults to `https://api.seliseblocks.com` unless `--blocks-api-url` is passed. Passing both `--app-domain` and `--client-id` skips the project lookup entirely (no login required). Writes nothing - use `new web` to scaffold a full app. |
 
 Use `--json` on commands when AI or automation needs machine-readable output. Use `--dry-run` before mutations and `--yes` only after approval.
 

package/dist/commands/data/schema/aggregation.js

@@ -6,6 +6,9 @@ import { parseCommand, selectedProject } from "../../../lib/workspace.js";
 export async function dataSchemaAggregation(argv) {
     const { flags } = parseCommand(argv);
     const projectKey = await selectedProject(flags);
+    const page = integerFlag(flags, "page", 1);
+    if (page < 1)
+        throw new Error("--page must be greater than or equal to 1");
     const result = await blocksRequest("/data/v4/schemas/aggregation", {
         impersonatedProjectAuth: true,
         ...requestContext(flags),
@@ -13,7 +16,7 @@ export async function dataSchemaAggregation(argv) {
         query: {
             CollectionName: stringFlag(flags, "collection-name") || undefined,
             Keyword: stringFlag(flags, "keyword") || undefined,
-            PageNo: integerFlag(flags, "page", 1),
+            PageNo: page,
             PageSize: integerFlag(flags, "page-size", 100),
             ProjectKey: projectKey,
             SchemaName: stringFlag(flags, "schema-name") || undefined,

package/dist/commands/deselect.js

@@ -1,31 +1,21 @@
-import { normalizeAccountName, readConfig } from "../lib/config.js";
-import { readTokenStore, writeTokenStore } from "../lib/token-store.js";
-import { requestContext } from "../lib/request-context.js";
+import { stringFlag } from "../lib/args.js";
+import { stopProjectImpersonation } from "../lib/auth.js";
+import { readConfig } from "../lib/config.js";
 import { clearSelectedProject, parseCommand } from "../lib/workspace.js";
 export async function deselectProject(argv) {
     const { flags } = parseCommand(argv);
+    const accountName = stringFlag(flags, "account") || undefined;
     const config = await readConfig();
-    const { accountName } = requestContext(flags);
-    const account = normalizeAccountName(accountName ?? config.activeAccount);
-    const tenantId = await clearSelectedProject();
+    const tenantId = config.selectedProject?.tenantId;
     if (!tenantId) {
         console.log("No project is currently selected.");
         return;
     }
-    const store = await readTokenStore();
-    const projects = store.accounts[account]?.projects;
-    if (projects && tenantId in projects) {
-        const { [tenantId]: _removed, ...remainingProjects } = projects;
-        await writeTokenStore({
-            accounts: {
-                ...store.accounts,
-                [account]: {
-                    ...store.accounts[account],
-                    projects: remainingProjects
-                }
-            }
-        });
-    }
-    console.log(`Deselected project tenant ${tenantId}.`);
+    // Stop-impersonation restores a fresh account refresh token and drops the
+    // project's cached token from the store, so there's nothing left to clean
+    // up here beyond the selection itself.
+    await stopProjectImpersonation(accountName, tenantId);
+    await clearSelectedProject();
+    console.log(`Deselected project tenant ${tenantId}. Account session restored.`);
     console.log("Run 'blocks use <tenantId>' to select a project again.");
 }

package/dist/commands/iam/me.js

@@ -4,8 +4,11 @@ import { requestContext } from "../../lib/request-context.js";
 import { parseCommand } from "../../lib/workspace.js";
 export async function iamMe(argv = []) {
     const { flags } = parseCommand(argv);
+    // The server resets to the root tenant's identity for this endpoint
+    // regardless of which token calls it, so the impersonated project session
+    // works fine here too -- prefer it when a project is selected.
     const me = await blocksRequest("/iam/v4/iam/me", {
-        accountAuth: true,
+        preferImpersonatedProjectAuth: true,
         ...requestContext(flags)
     });
     writeOutput(me, { ...flags, json: true });

package/dist/commands/iam/permissions/list.js

@@ -1,4 +1,4 @@
-import { integerFlag, optionalBooleanFlag, optionalIntegerFlag, stringFlag } from "../../../lib/args.js";
+import { booleanFlag, integerFlag, optionalBooleanFlag, optionalIntegerFlag, stringFlag } from "../../../lib/args.js";
 import { blocksRequest } from "../../../lib/api.js";
 import { compact, jsonBodyFlag, listFlag } from "../../../lib/json-flag.js";
 import { writeOutput } from "../../../lib/output.js";
@@ -7,6 +7,7 @@ import { parseCommand, selectedProject } from "../../../lib/workspace.js";
 export async function iamPermissionsList(argv) {
     const { flags } = parseCommand(argv);
     const projectKey = await selectedProject(flags);
+    const sortBy = stringFlag(flags, "sort-by");
     const filter = {
         ...(await jsonBodyFlag(flags)).filter,
         ...compact({
@@ -23,13 +24,13 @@ export async function iamPermissionsList(argv) {
     const body = {
         filter,
         organizationId: stringFlag(flags, "organization-id") || undefined,
-        page: integerFlag(flags, "page", 1),
+        page: iamBackendPage(flags),
         pageSize: integerFlag(flags, "page-size", 20),
         roles: listFlag(flags, "roles"),
-        sort: {
-            isDescending: stringFlag(flags, "sort-desc") === "true",
-            property: stringFlag(flags, "sort-by") || undefined
-        }
+        sort: sortBy ? {
+            isDescending: booleanFlag(flags, "sort-desc"),
+            property: sortBy
+        } : undefined
     };
     const result = await blocksRequest("/iam/v4/iam/permissions", {
         body,
@@ -39,3 +40,9 @@ export async function iamPermissionsList(argv) {
     });
     writeOutput(result, flags);
 }
+function iamBackendPage(flags) {
+    const page = integerFlag(flags, "page", 1);
+    if (page < 1)
+        throw new Error("--page must be greater than or equal to 1");
+    return page - 1;
+}

package/dist/commands/iam/roles/assign-permissions.js

@@ -8,10 +8,13 @@ import { parseCommand, selectedProject } from "../../../lib/workspace.js";
 export async function iamRolesAssignPermissions(argv) {
     const { args, flags } = parseCommand(argv);
     const slug = args[0] || stringFlag(flags, "slug", { required: true });
+    const addPermissions = listFlag(flags, "add-permissions");
+    const removePermissions = listFlag(flags, "remove-permissions");
+    const organizationId = stringFlag(flags, "organization-id") || undefined;
     const body = {
-        addPermissions: listFlag(flags, "add-permissions"),
-        oragnizationId: stringFlag(flags, "organization-id") || undefined,
-        removePermissions: listFlag(flags, "remove-permissions"),
+        addPermissions,
+        organizationId,
+        removePermissions,
         slug
     };
     if (!body.addPermissions && !body.removePermissions) {
@@ -21,13 +24,71 @@ export async function iamRolesAssignPermissions(argv) {
         writeOutput({ dryRun: true, endpoint: "/iam/v4/iam/roles/assign-permissions", request: body }, flags);
         return;
     }
-    await confirmMutation(flags, `Change permission assignments for IAM role '${slug}'.`);
     const projectKey = await selectedProject(flags);
+    const resolvedBody = {
+        ...body,
+        addPermissions: await resolvePermissionIdentifiers(addPermissions, organizationId, flags, projectKey),
+        removePermissions: await resolvePermissionIdentifiers(removePermissions, organizationId, flags, projectKey)
+    };
+    await confirmMutation(flags, `Change permission assignments for IAM role '${slug}'.`);
     const result = await blocksRequest("/iam/v4/iam/roles/assign-permissions", {
-        body,
+        body: resolvedBody,
         impersonatedProjectAuth: true,
         ...requestContext(flags),
         projectTenantId: projectKey
     });
     writeOutput(result, flags);
 }
+async function resolvePermissionIdentifiers(identifiers, organizationId, flags, projectKey) {
+    if (!identifiers?.length)
+        return identifiers;
+    const resources = identifiers.filter((item) => item.includes("::"));
+    if (resources.length === 0)
+        return identifiers;
+    const response = await blocksRequest("/iam/v4/iam/permissions", {
+        body: {
+            filter: {
+                isArchived: false,
+                resources
+            },
+            organizationId,
+            page: 0,
+            pageSize: Math.max(resources.length, 20)
+        },
+        impersonatedProjectAuth: true,
+        ...requestContext(flags),
+        projectTenantId: projectKey
+    });
+    const permissions = extractPermissionRows(response);
+    const byResource = new Map();
+    for (const permission of permissions) {
+        const resource = stringProperty(permission, "resource");
+        const itemId = stringProperty(permission, "itemId") || stringProperty(permission, "_id") || stringProperty(permission, "id");
+        if (resource && itemId)
+            byResource.set(resource, itemId);
+    }
+    const missing = resources.filter((resource) => !byResource.has(resource));
+    if (missing.length > 0) {
+        throw new Error(`Could not resolve IAM permission resource(s) to itemId: ${missing.join(", ")}`);
+    }
+    return identifiers.map((identifier) => byResource.get(identifier) ?? identifier);
+}
+function extractPermissionRows(response) {
+    if (Array.isArray(response))
+        return response.filter(isRecord);
+    if (!isRecord(response))
+        return [];
+    for (const key of ["data", "Data", "items", "Items", "permissions", "Permissions"]) {
+        const value = response[key];
+        if (Array.isArray(value))
+            return value.filter(isRecord);
+    }
+    return [];
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function stringProperty(record, name) {
+    const value = record[name] ?? record[name[0].toUpperCase() + name.slice(1)];
+    return typeof value === "string" ? value : "";
+}

package/dist/commands/iam/roles/list.js

@@ -1,4 +1,4 @@
-import { integerFlag, stringFlag } from "../../../lib/args.js";
+import { booleanFlag, integerFlag, stringFlag } from "../../../lib/args.js";
 import { blocksRequest } from "../../../lib/api.js";
 import { compact, jsonBodyFlag, listFlag } from "../../../lib/json-flag.js";
 import { writeOutput } from "../../../lib/output.js";
@@ -7,6 +7,7 @@ import { parseCommand, selectedProject } from "../../../lib/workspace.js";
 export async function iamRolesList(argv) {
     const { flags } = parseCommand(argv);
     const projectKey = await selectedProject(flags);
+    const sortBy = stringFlag(flags, "sort-by");
     const filter = {
         ...(await jsonBodyFlag(flags)).filter,
         ...compact({
@@ -17,12 +18,12 @@ export async function iamRolesList(argv) {
     const body = {
         filter,
         organizationId: stringFlag(flags, "organization-id") || undefined,
-        page: integerFlag(flags, "page", 1),
+        page: iamBackendPage(flags),
         pageSize: integerFlag(flags, "page-size", 20),
-        sort: {
-            isDescending: stringFlag(flags, "sort-desc") === "true",
-            property: stringFlag(flags, "sort-by") || undefined
-        }
+        sort: sortBy ? {
+            isDescending: booleanFlag(flags, "sort-desc"),
+            property: sortBy
+        } : undefined
     };
     const result = await blocksRequest("/iam/v4/iam/roles", {
         body,
@@ -32,3 +33,9 @@ export async function iamRolesList(argv) {
     });
     writeOutput(result, flags);
 }
+function iamBackendPage(flags) {
+    const page = integerFlag(flags, "page", 1);
+    if (page < 1)
+        throw new Error("--page must be greater than or equal to 1");
+    return page - 1;
+}

package/dist/commands/login.js

@@ -1,9 +1,11 @@
 import { parseFlags, stringFlag } from "../lib/args.js";
-import { pollDeviceToken, requestDeviceAuthorization } from "../lib/auth.js";
+import { getImpersonatedProjectSession, pollDeviceToken, requestDeviceAuthorization } from "../lib/auth.js";
 import { getAccountProfile, readConfig, writeConfig } from "../lib/config.js";
 import { openBrowser } from "../lib/open-browser.js";
+import { listProjectGroups } from "../lib/project-info.js";
 import { applyAccountToken } from "../lib/token.js";
 import { readTokenStore, writeTokenStore } from "../lib/token-store.js";
+import { readWorkspaceConfig } from "../lib/workspace.js";
 export async function login(argv) {
     const { flags } = parseFlags(argv);
     const accountOverride = stringFlag(flags, "account");
@@ -32,4 +34,33 @@ export async function login(argv) {
     await writeConfig(next.config);
     await writeTokenStore(next.store);
     console.log("Login done.");
+    const workspace = await readWorkspaceConfig();
+    const rememberedTenantId = workspace.project?.tenantId ?? next.config.selectedProject?.tenantId;
+    if (rememberedTenantId) {
+        try {
+            await getImpersonatedProjectSession(name, rememberedTenantId);
+            console.log(`Re-selected project tenant ${rememberedTenantId}.`);
+        }
+        catch (error) {
+            console.log(`Could not re-select project tenant ${rememberedTenantId}: ${error instanceof Error ? error.message : String(error)}`);
+            console.log("Run 'blocks use <tenantId>' to select a project.");
+        }
+        return;
+    }
+    try {
+        const groups = await listProjectGroups(flags);
+        const projects = groups.flatMap((group) => group.projects ?? []);
+        if (projects.length === 0) {
+            console.log("No projects found for this account.");
+            return;
+        }
+        console.log("Available projects:");
+        for (const project of projects) {
+            console.log(`  ${project.tenantId ?? "-"}  ${project.name ?? "-"}  ${project.environment ?? "-"}`);
+        }
+        console.log("Run 'blocks use <tenantId>' to select one.");
+    }
+    catch (error) {
+        console.log(`Could not list projects: ${error instanceof Error ? error.message : String(error)}`);
+    }
 }

package/dist/commands/new/web.js

@@ -2,6 +2,7 @@ import { stringFlag } from "../../lib/args.js";
 import { blocksRequest } from "../../lib/api.js";
 import { confirmMutation } from "../../lib/confirm.js";
 import { defaults, readConfig, writeConfig } from "../../lib/config.js";
+import { apiUrlFromAppDomain } from "../../lib/domains.js";
 import { CliActionableError } from "../../lib/errors.js";
 import { findProjectByTenantId } from "../../lib/project-info.js";
 import { promptText, selectFromList } from "../../lib/prompt.js";
@@ -16,9 +17,9 @@ export async function newWeb(argv) {
     const tenantId = stringFlag(flags, "x-blocks-key") || (await selectedProject(flags));
     const explicitAppDomain = stringFlag(flags, "app-domain");
     const project = explicitAppDomain ? {} : (await findProjectByTenantId(tenantId, flags)).project;
-    const apiUrl = stringFlag(flags, "blocks-api-url", { defaultValue: defaults().apiUrl });
     const oidcUrl = stringFlag(flags, "oidc-url", { defaultValue: defaults().oidcUrl });
     const appDomain = await resolveAppDomain(project, flags);
+    const apiUrl = stringFlag(flags, "blocks-api-url") || apiUrlFromAppDomain(appDomain);
     const oidcClientId = await resolveOidcClientId(tenantId, appDomain, name, flags);
     await scaffoldWebProject({
         apiUrl,

package/dist/commands/secrets/save.js

@@ -45,7 +45,7 @@ function redactSecret(body) {
         return body;
     const redacted = {};
     for (const [key, value] of Object.entries(pairs)) {
-        redacted[key] = /secret|password|key$/i.test(key) ? "***" : value;
+        redacted[key] = /(secret|password|key$)/i.test(key) ? "***" : value;
     }
     return { ...body, keyValuePairs: redacted };
 }

package/dist/commands/use.js

@@ -1,9 +1,24 @@
-import { saveSelectedProject } from "../lib/workspace.js";
+import { stringFlag } from "../lib/args.js";
+import { getImpersonatedProjectSession, stopProjectImpersonation } from "../lib/auth.js";
+import { readConfig } from "../lib/config.js";
+import { parseCommand, saveSelectedProject } from "../lib/workspace.js";
 export async function useProject(argv) {
-    const tenantId = argv[0];
+    const { args, flags } = parseCommand(argv);
+    const tenantId = args[0];
     if (!tenantId)
         throw new Error("Missing project tenant id.");
+    const accountName = stringFlag(flags, "account") || undefined;
+    const config = await readConfig();
+    const previousTenantId = config.selectedProject?.tenantId;
+    if (previousTenantId && previousTenantId !== tenantId) {
+        // Switching projects needs a fresh account refresh token to start the new
+        // impersonation -- the one used to start the old impersonation was
+        // already consumed by the server, so the old session must be stopped
+        // first to get a new one back.
+        await stopProjectImpersonation(accountName, previousTenantId);
+    }
     await saveSelectedProject(tenantId);
+    const project = await getImpersonatedProjectSession(accountName, tenantId);
     console.log(`Selected project tenant ${tenantId}`);
-    console.log("Root/account session is kept for OS project APIs. Project impersonation is created lazily when a service command needs it.");
+    console.log(`Project session ready for tenant ${project.tenantId}.`);
 }

package/dist/index.js

@@ -500,7 +500,9 @@ Auth:
     Device-code login. Prints a verification URL and user code, opens the
     browser to the verification page when possible so you only need to click
     approve, then polls until the device is authorized; stores account access
-    and refresh tokens and auto-refreshes later.
+    and refresh tokens and auto-refreshes later. If a project was previously
+    selected, re-impersonates it automatically; otherwise lists projects and
+    prompts you to run 'blocks use <tenantId>'.
 
   blocks auth status [--json]
     Show only whether account/project access and refresh tokens are missing,
@@ -518,8 +520,9 @@ Auth:
 
 Projects:
   blocks projects list [--json]
-    List accessible Blocks projects via /os/v4/Project/Gets using the account
-    token. Read-only.
+    List accessible Blocks projects via /os/v4/Project/Gets. Uses the
+    impersonated project session when a project is selected, otherwise the
+    account token. Read-only.
 
   blocks projects get [tenantId] [--deployment] [--json]
     Read one project from Project/Gets. Uses selected project when tenantId is
@@ -528,20 +531,24 @@ Projects:
     to resolve its target. Read-only.
 
   blocks use <project-tenant-id>
-    Save the selected project tenant globally and in blocks.json when present.
-    Does not call cloud APIs.
+    Save the selected project tenant globally and in blocks.json when present,
+    then immediately impersonate it. If a different project was selected,
+    stops that impersonation first to reclaim a fresh account refresh token
+    before starting the new one.
 
   blocks deselect
-    Clear the selected project tenant (globally and in blocks.json) and drop
-    its cached impersonation token. Use this to recover when an impersonated
-    project token has expired or failed, then run 'blocks use <tenantId>'
-    again to reselect and re-impersonate.
+    Stop the active impersonation (restoring a fresh account refresh token),
+    then clear the selected project tenant (globally and in blocks.json) and
+    drop its cached impersonation token. Run 'blocks use <tenantId>' again to
+    reselect and re-impersonate.
 
 IAM:
   blocks iam me [--json]
-    Read the current user from IAM using the account token (bootstrapping/CLI
-    operator identity, not a project resource). Every other iam * command below
-    is project-scoped: it requires a selected project and calls IAM using an
+    Read the current user from IAM (bootstrapping/CLI operator identity, not
+    a project resource). Uses the impersonated project session when a project
+    is selected, otherwise the account token -- the server always resolves
+    this to the root identity either way. Every other iam * command below is
+    project-scoped: it requires a selected project and calls IAM using an
     impersonated project token only, never the account token.
 
   Users (/iam/v4/iam/users*):
@@ -1082,9 +1089,11 @@ Scaffold:
     name + redirect URI, active, registered as a Blocks OIDC identity
     provider) on the spot, or skip and register one later from the portal or
     'auth oidc-clients save'.
-    --blocks-api-url defaults to https://api.seliseblocks.com if omitted -
-    pass a different Data/IAM/Localization/OS gateway URL explicitly only if
-    your project uses a non-default one.
+    If --blocks-api-url is omitted, it is derived from the app domain:
+    https://blocksapi.<registrable-domain> (for example, app domain
+    https://dqrsf.slsblx.com uses https://blocksapi.slsblx.com). Pass a
+    different Data/IAM/Localization/OS gateway URL explicitly only if your
+    project uses a non-default one.
     --oidc-url defaults to https://iam.seliseblocks.com.
 
 Skills:
@@ -1102,11 +1111,12 @@ Skills:
 SDK:
   blocks sdk client [--app-domain <domain>] [--client-id <oidcClientId>]
                     [--x-blocks-key <tenantId>] [--blocks-api-url <url>] [--oidc-url <url>] [--json]
-    Read-only: "I want to use the Blocks SDK -- show me the client." Resolves this
-    project's @seliseblocks/client config (same values 'new web' scaffolds with,
-    using the selected project unless --x-blocks-key overrides it, and the
-    project's registered domain/OIDC client when --app-domain/--client-id are
-    omitted) and prints a ready-to-paste createBlocksClient(...) snippet.
+    Read-only: "I want to use the Blocks SDK -- show me the client." Resolves this
+    project's @seliseblocks/client config using the selected project unless
+    --x-blocks-key overrides it, and the project's registered domain/OIDC client
+    when --app-domain/--client-id are omitted. Its API URL defaults to
+    https://api.seliseblocks.com unless --blocks-api-url is passed.
+    Prints a ready-to-paste createBlocksClient(...) snippet.
     Passing both --app-domain and --client-id skips the project lookup entirely
     (no login required). Never writes a file; to scaffold a new app use 'new web'.
 `);

package/dist/lib/api.d.ts

@@ -5,6 +5,7 @@ type RequestOptions = {
     body?: unknown;
     impersonatedProjectAuth?: boolean;
     method?: string;
+    preferImpersonatedProjectAuth?: boolean;
     projectTenantId?: string;
     query?: Record<string, string | number | boolean | string[] | undefined>;
 };

package/dist/lib/api.js

@@ -31,8 +31,26 @@ export async function blocksRequest(path, options = {}) {
         if (options.impersonatedProjectAuth) {
             const project = await getImpersonatedProjectSession(options.accountName, options.projectTenantId, { forceRefresh });
             headers.Authorization = `Bearer ${project.accessToken}`;
+            // The impersonated token is minted and signed by the root tenant's IdP --
+            // its JWKS only exists under the root tenant, so signature validation
+            // needs x-blocks-key pointed at root, not the target project. The actual
+            // tenant-data scoping comes from a claim already inside the validated
+            // token, not from this header.
             headers["x-blocks-key"] = project.accountTenant;
         }
+        if (options.preferImpersonatedProjectAuth) {
+            const tenantId = options.projectTenantId ?? config.selectedProject?.tenantId;
+            if (tenantId) {
+                const project = await getImpersonatedProjectSession(options.accountName, tenantId, { forceRefresh });
+                headers.Authorization = `Bearer ${project.accessToken}`;
+                headers["x-blocks-key"] = project.accountTenant;
+            }
+            else {
+                const account = await getAccountSession(options.accountName, { forceRefresh });
+                headers.Authorization = `Bearer ${account.accessToken}`;
+                headers["x-blocks-key"] = account.accountTenant;
+            }
+        }
         return fetch(url, {
             body: options.body === undefined ? undefined : isFormData ? options.body : JSON.stringify(options.body),
             headers,
@@ -41,14 +59,22 @@ export async function blocksRequest(path, options = {}) {
             throw new Error(`Blocks API request failed for ${url.origin}${url.pathname}: ${error.message}`);
         });
     };
+    const method = options.method ?? (options.body === undefined ? "GET" : "POST");
     let response = await send(false);
-    if (response.status === 401 && (options.accountAuth || options.impersonatedProjectAuth)) {
+    if (response.status === 401 && (options.accountAuth || options.impersonatedProjectAuth || options.preferImpersonatedProjectAuth)) {
         // The locally cached expiry said the token was still good, but the server
         // rejected it anyway (early revocation, clock skew, forced logout server-side).
         // Force one refresh-and-retry before giving up -- this is what actually
         // prevents a spurious 're-run blocks login' when the refresh token is still valid.
         response = await send(true);
     }
+    else if (response.status === 500 && method === "GET") {
+        // Some tenant-scoped read endpoints (mfa config, signup-settings) intermittently
+        // 500 with a JWKS/kid lookup failure right after impersonation, then succeed on
+        // an immediate identical retry once the signing-key cache catches up. Safe to
+        // retry blindly here because GET is idempotent.
+        response = await send(false);
+    }
     const text = await response.text();
     const data = parseJson(text);
     if (!response.ok) {

package/dist/lib/auth.d.ts

@@ -31,4 +31,5 @@ export declare function pollDeviceToken(profile: AccountProfile, device: DeviceA
 export declare function getAccountSession(accountOverride?: string, options?: SessionOptions): Promise<AccountSession>;
 export declare function selectProject(tenantId: string): Promise<void>;
 export declare function getImpersonatedProjectSession(accountOverride?: string, tenantOverride?: string, options?: SessionOptions): Promise<ProjectSession>;
+export declare function stopProjectImpersonation(accountOverride?: string, tenantOverride?: string): Promise<void>;
 export declare function revokeCurrentSession(accountOverride?: string): Promise<void>;

package/dist/lib/auth.js

@@ -194,6 +194,57 @@ export async function getImpersonatedProjectSession(accountOverride, tenantOverr
     await writeTokenStore(next.store);
     return projectSessionFromToken(name, tenantId, next.store.accounts[name].projects[tenantId], account.accountTenant);
 }
+// Ends the active project impersonation and restores a fresh, refreshable
+// account-level session. The IAM server revokes the account refresh token the
+// moment it's used to start an impersonation (see impersonateProject) and
+// only ever hands back a project-scoped one in exchange -- calling
+// '/impersonation/stop' is the only way to get a new account-level refresh
+// token back. No-ops if no project is selected or nothing was ever
+// impersonated for it.
+export async function stopProjectImpersonation(accountOverride, tenantOverride) {
+    const config = await readConfig();
+    const { name, profile } = getAccountProfile(config, accountOverride);
+    const tenantId = tenantOverride ?? config.selectedProject?.tenantId;
+    if (!tenantId)
+        return;
+    const store = await readTokenStore();
+    if (!store.accounts[name]?.projects?.[tenantId]?.refreshToken)
+        return;
+    // The stop endpoint requires a currently-valid bearer token to authenticate
+    // the call, so refresh the project session first if it's expiring.
+    const project = await getImpersonatedProjectSession(name, tenantId);
+    const beforeStop = await readTokenStore();
+    const projectToken = beforeStop.accounts[name]?.projects?.[tenantId];
+    if (!projectToken?.refreshToken)
+        return;
+    const refreshed = await postStopImpersonation(profile.apiUrl, project.accessToken, project.accountTenant, projectToken.refreshToken);
+    const latestConfig = await readConfig();
+    const latestStore = await readTokenStore();
+    const next = applyAccountToken(latestConfig, latestStore, name, profile.clientId, refreshed);
+    const { [tenantId]: _removed, ...remainingProjects } = next.store.accounts[name]?.projects ?? {};
+    next.store.accounts[name] = {
+        ...next.store.accounts[name],
+        projects: remainingProjects
+    };
+    await writeConfig(next.config);
+    await writeTokenStore(next.store);
+}
+async function postStopImpersonation(apiUrl, accessToken, accountTenant, refreshToken) {
+    const response = await fetch(new URL("/iam/v4/auth/impersonation/stop", apiUrl), {
+        body: JSON.stringify({ refresh_token: refreshToken }),
+        headers: {
+            Accept: "application/json",
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+            "x-blocks-key": accountTenant
+        },
+        method: "POST"
+    });
+    const data = parseJson(await response.text());
+    if (response.ok && !data.error)
+        return data;
+    throw new Error(data.error_description ?? data.error ?? `Stop impersonation failed with HTTP ${response.status}`);
+}
 export async function revokeCurrentSession(accountOverride) {
     const config = await readConfig();
     const store = await readTokenStore();

package/dist/lib/domains.d.ts

@@ -0,0 +1,2 @@
+export declare function hostFromAppDomain(appDomain: string): string;
+export declare function apiUrlFromAppDomain(appDomain: string): string;

package/dist/lib/domains.js

@@ -0,0 +1,14 @@
+export function hostFromAppDomain(appDomain) {
+    try {
+        return new URL(appDomain).host;
+    }
+    catch {
+        return appDomain.replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+    }
+}
+export function apiUrlFromAppDomain(appDomain) {
+    const hostname = hostFromAppDomain(appDomain).split(":")[0].toLowerCase();
+    const labels = hostname.split(".").filter(Boolean);
+    const registrableDomain = labels.length >= 2 ? labels.slice(-2).join(".") : hostname;
+    return `https://blocksapi.${registrableDomain}`;
+}

package/dist/lib/project-info.js

@@ -1,12 +1,16 @@
 import { blocksRequest } from "./api.js";
 import { requestContext } from "./request-context.js";
 import { selectedProject } from "./workspace.js";
-// Project metadata (Project/Gets, Project/GetAsset) always uses the account
-// token, never the impersonated project token -- these endpoints operate at
-// the account/tenant-group level, above any single project's own API surface.
+// Project metadata (Project/Gets, Project/GetAsset) is authorized at the
+// account/tenant-group level, above any single project's own API surface --
+// but the platform's permission check rebuilds to the root tenant while
+// impersonating, and the underlying query filters by user id rather than
+// tenant, so the impersonated project session works here too. Prefer it when
+// a project is selected (avoids an extra account-session refresh mid-project
+// work); fall back to the account token when nothing is selected yet.
 export async function listProjectGroups(flags) {
     return blocksRequest("/os/v4/Project/Gets", {
-        accountAuth: true,
+        preferImpersonatedProjectAuth: true,
         query: { page: 0, pageSize: 100, tenantGroupId: "" },
         ...requestContext(flags)
     });
@@ -32,7 +36,7 @@ export async function resolveSelectedProject(flags) {
 }
 export async function getProjectAssets(tenantGroupId, flags) {
     return blocksRequest("/os/v4/Project/GetAsset", {
-        accountAuth: true,
+        preferImpersonatedProjectAuth: true,
         query: { page: 0, pageSize: 100, tenantGroupId },
         ...requestContext(flags)
     });

package/dist/lib/scaffold-web/fs.d.ts

@@ -1,2 +1,3 @@
+import { hostFromAppDomain } from "../domains.js";
+export { hostFromAppDomain };
 export declare function write(root: string, path: string, content: string): Promise<void>;
-export declare function hostFromAppDomain(appDomain: string): string;

package/dist/lib/scaffold-web/fs.js

@@ -1,15 +1,9 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { hostFromAppDomain } from "../domains.js";
+export { hostFromAppDomain };
 export async function write(root, path, content) {
     const fullPath = join(root, path);
     await mkdir(dirname(fullPath), { recursive: true });
     await writeFile(fullPath, `${content.endsWith("\n") ? content : `${content}\n`}`);
 }
-export function hostFromAppDomain(appDomain) {
-    try {
-        return new URL(appDomain).host;
-    }
-    catch {
-        return appDomain.replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-    }
-}

package/dist/lib/scaffold-web/root-files.js

@@ -18,7 +18,7 @@ export async function writeRootFiles(root, options) {
         },
         dependencies: {
             "@radix-ui/react-dropdown-menu": "^2.1.24",
-            "@seliseblocks/client": "^0.1.1",
+            "@seliseblocks/client": "^0.1.3",
             "@tanstack/react-query": "^5.101.4",
             clsx: "^2.1.1",
             "lucide-react": "^1.28.0",

package/dist/skills/blocks-iam-access-control/flows/manage-roles-permissions.md

@@ -103,6 +103,7 @@ blocks iam roles assign-permissions editor --add-permissions content::publish --
 
 - **CLI mutations are project-scoped, not account-scoped** — `blocks iam roles create/update/assign-permissions` and `blocks iam permissions create/update` all require a selected project (`blocks use <tenantId>` or `--project <tenantId>`) and run against the impersonated-project token; `blocks iam me` is the one IAM command that uses the account token instead, so don't expect `iam me`'s auth context to carry over to these.
 - **Role hierarchy and permission assignment key off `slug`**, not `itemId` — grab it from `roles.list()`/`roles.get()` (or `blocks iam roles list/get`) before calling `assignPermissions`.
+- **Permission assignment ultimately uses permission `itemId`s** — the CLI resolves `resource` strings like `content::publish` before mutation; SDK/backend callers should pass permission ids directly in `addPermissions` / `removePermissions`.
 - **`roles.assignPermissions` is additive/subtractive** (`addPermissions[]` / `removePermissions[]` in one call), not a full-set replace — compute the delta from what's checked/unchecked, don't resend the entire permission list as "adds."
 - **`roles.assignable()` scopes to the caller** — always populate role pickers from it rather than `roles.list()`, so an admin can't be shown (or attempt to grant) a role above their own authority.
 - **Never fire a create/update/assign-permissions call — CLI or SDK — without a human confirming that specific change first** (a reviewed `--dry-run` plus explicit go-ahead on the CLI, an explicit in-UI confirm for the SDK) — no auto-provisioning "default roles," no agent-initiated cleanup of permissions, no batch edits without a per-change confirm.

package/dist/skills/blocks-onboarding/SKILL.md

@@ -66,7 +66,7 @@ Run `blocks init` once per project directory to create `blocks.json`, `blocks/da
 Then route to what the user actually wants:
 - Building a frontend from scratch → resolve the app's public OIDC client first, then scaffold:
   - `blocks auth oidc-clients list --json` — check whether a client already registered for this project fits. If none fits, create one directly (no portal visit needed): `blocks auth oidc-clients save --client-display-name <appName> --redirect-uris https://<domain>:5173/login/callback --scope "openid profile" --require-pkce --register-as-identity-provider --dry-run --json`, then re-run with `--yes` after showing the dry-run output and getting approval. See the blocks-iam-sso-oidc-configuration skill for the full decision tree and field-level gotchas.
-  - `blocks new web <name> --x-blocks-key <tenantId> --app-domain <domain> --blocks-api-url https://api.seliseblocks.com --client-id <the-resolved-client-id>`. **Always pass `--client-id` and `--app-domain` explicitly** — omitting either drops `new web` into an interactive pick-list prompt with no non-interactive escape (not even to "skip"), which hangs a scripted/agent run with no stdin to answer it.
+  - `blocks new web <name> --x-blocks-key <tenantId> --app-domain <domain> --client-id <the-resolved-client-id>`. **Always pass `--client-id` and `--app-domain` explicitly** — omitting either drops `new web` into an interactive pick-list prompt with no non-interactive escape (not even to "skip"), which hangs a scripted/agent run with no stdin to answer it. Omit `--blocks-api-url` unless the project uses a non-default gateway; the scaffold derives it from the app domain, e.g. `https://dqrsf.slsblx.com` -> `https://blocksapi.slsblx.com`.
 - Defining data / CRUD / localization / release on an existing project → hand off to the matching skill; the project is already selected via `blocks use`, so its commands can proceed directly.
 
 ## Gotchas

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seliseblocks/cli-os",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "CLI for SELISE Blocks project setup and configuration.",
   "license": "MIT",
   "type": "module",