Blocks — Bootstrap

Purpose

Every other Blocks skill assumes three things are already true: the blocks CLI is installed, the user is logged in, and a project is selected. This skill establishes those, then routes to whichever flow the user actually needs.

It ends at one user can log into the app. Ongoing user administration after that belongs to blocks-iam-users, blocks-iam-account, and blocks-iam-organizations.

Everything here goes through blocks. Never a raw fetch/curl against a Blocks API, and never a workaround that skips the CLI's confirmation and dry-run discipline.

When to use

• The user mentions SELISE Blocks and their login/project/app state is unknown.
• A command failed with not_logged_in, project_not_selected, api_auth_failed, or refresh_token_rejected.
• The user wants to build on Blocks and has not said where they are starting from.
• The user handed you an x-blocks-key and expects you to pick that project up.
• The user asks to log the CLI out of Blocks or clear the current CLI session.

Once the CLI is logged in, a project is selected, and the user is asking for a specific capability (data schemas, localization, mail, storage, roles), that capability's own skill owns the work — hand off rather than continuing here.

State detection — probe, don't interrogate

Minimum CLI version: 0.11.0. Every Blocks skill is checked against this version of blocks or newer; an older CLI is missing commands and flags they cite.

Run all four before asking the user anything. None of them mutates, and none prints a token value. (npm view is a public registry lookup; if it fails offline, continue without the comparison.)

blocks --version
npm view @seliseblocks/cli-os version
blocks auth status --json
blocks doctor --json

auth status reports only existence and freshness — missing, expired, valid, or available (present, but with no recorded expiry) — for four tokens:

{ "accountAccessToken": "expired", "accountRefreshToken": "missing",
  "projectAccessToken": "expired", "projectRefreshToken": "valid" }

The resolved account persists one exclusive mode: account AT+RT, or one project's AT+RT. Missing account tokens while the project pair is valid is normal project mode, not a broken login. Read it like this:

A selected project does not prove a usable session. Selection is metadata; project mode is usable only when its project token pair is present. Do not require an account pair simultaneously: impersonation replaces it, and blocks deselect exchanges the project pair for a fresh account pair.

From CLI 0.3.2 onward, any command may print an Update available notice on stderr, and blocks doctor --json reports cliUpdateAvailable. Treat either exactly like the version comparison above: inform the user, ask for confirmation, and only then update.

Use blocks doctor --json when something looks broken rather than merely undone — it checks Node version, credential storage backend, account and project token freshness in one pass. Its detail fields include the paths of the CLI's config and secret files. That is diagnostic output, not an invitation: never open, read, print, or quote those files. Interact with them only through blocks commands.

If credential storage itself is unreadable or corrupted (machine migration, Windows profile change, Keychain reset), run blocks auth remove <account>, then blocks login --account <account> locally. Never copy credentials from another account or config directory.

Agent execution context

Local agent

Do not set BLOCKS_CONFIG_DIR for ordinary local work. Reuse the user's normal OS-scoped CLI context and interact with it only through blocks commands. Probe first. If no account is active in a non-interactive run, ask which account to use; never pick another configured account. Run device login yourself with an explicit name, relay the verification URL/code, and keep the process running while the user approves it:

blocks login --account <name>
blocks auth status --account <name> --json

If the user supplied a tenant, use it. Otherwise list projects and ask before changing selection. Once known, AI automation should pass both contexts explicitly even though interactive local use may rely on activeAccount:

blocks use <tenantId> --account <name>
blocks <command> --account <name> --project <tenantId> --json

Use a temporary BLOCKS_CONFIG_DIR only when the user explicitly asks to test isolation or a package build. A new directory is intentionally unauthenticated; never copy the user's normal tokens into it.

Code Studio agent

The launcher, not the agent, owns installation, isolation, and authentication bootstrap. Never unset, replace, or guess BLOCKS_CONFIG_DIR. Start with blocks auth status --json. If context/auth is missing, report that the Studio session was not bootstrapped; do not fall back to OS state, inspect storage, or copy credentials from another session. Device login is acceptable only when the Studio product explicitly supports user approval for that isolated session. Fully unattended Studio startup requires a launcher/backend bootstrap feature; the current CLI does not provide one.

Log in

If the user has never used SELISE Blocks at all, they need an account before this will work. Send them to https://os.seliseblocks.com to sign up, wait for them to confirm the account exists, then log in. Do not run blocks login first and let them discover the problem at the verification page.

blocks login --account <name>

The CLI authenticates itself with no setup: there is nothing to register in a portal first, no client id or secret to collect from the user, and nothing about how it authenticates to look up or report. It prints a verification URL and user code, opens the browser to the verification page when it can, then polls until authorized and stores account tokens that refresh themselves afterwards.

Run it yourself rather than only telling the user to run it, so you can read the printed code and URL back to them and confirm the result. Verify with blocks auth status --json afterwards — do not assume it worked.

Log out

For "log me out of Blocks", run blocks logout for the resolved account. It revokes the current refresh token where possible and clears that account's local session data from the resolved config store. In automation, pass --account <name> explicitly; never log out a different configured account. Verify with blocks auth status --account <name> --json.

Routing

A user starting from nothing usually walks it in this order: project selection → OIDC client (and social provider, if they want it) → new web app → first user. Someone handed a key and asking what exists starts at project selection, then the inventory flow, and goes wherever its gap list points.

Once one user can log in, bootstrap is over. Hand off to each capability's own skill for data, localization, mail, storage, IAM, and release work, and to blocks-iam-users/blocks-iam-account for further user work.

Two skills are deliberately not on the build path — blocks new web already wires both correctly, so loading them by default is wasted reading:

• blocks-iam-sso-oidc-implementation — only when hosted login misbehaves, or the user is extending the scaffolded auth flow. A scaffold whose login works needs nothing from it.
• blocks-frontend-local-https — only when actually setting up the local HTTPS dev loop (hosts entry, cert, dev server).

Hard rules

• Ask the user before installing or upgrading the global CLI. Never run npm install -g on your own initiative.
• If the user supplied an x-blocks-key, use it directly. Do not show a picker, and do not list projects to "confirm" a choice they already made.
• If they did not, list the projects and ask. Never silently continue on a prior session's cached selection.
• --dry-run before --yes on every cloud mutation. Show the user the exact action, then wait for approval. Never add --yes to a call they have not approved.
• Never expose secrets, tokens, refresh tokens, client secrets, cookies, JWTs, or passwords — not in output, not in files, not in commits.
• Never invent a project key, domain, API URL, or client id. If you cannot read it from a command, ask.
• Treat a GraphQL response carrying an errors array as a failure even when the HTTP status is 200.
• An unknown command or flag usually means the CLI is outdated. Compare blocks --version against npm view @seliseblocks/cli-os version before working around it.
• Run CLI commands sequentially per config directory. Authentication transitions are mutex-protected; parallel invocations can fail with auth_transition_busy.

Known error codes