@sequenceholdings/studio-cli — seq-studio

Standalone CLI for the Sequence platform: typed agents, Lattice processes, Artifact Studio apps, Managed Functions, Managed Secrets, ORM namespaces, Data Pipelines stage specs, and platform git repos. Its published workflows run from any repo against the platform over HTTP — no monorepo checkout required. The v0 app-monorepo commands below are currently internal; see their availability notice.

seq-studio process lint
seq-studio process plan -e <env>
seq-studio process apply -e <env>
seq-studio agents validate
seq-studio agents plan -e <env>
seq-studio artifact deploy -e <env>
seq-studio orm init lending
seq-studio pipeline validate
seq-studio envs list
seq-studio doctor

Note: all network commands require a Sequence platform account with the appropriate permissions. Without one, only the offline commands (init, lint, simulate, build, bundle inspect, agents init, agents validate, offline agents plan, pipeline init, pipeline validate) work. Sequence-internal contributors: see INTERNAL.md in the monorepo for rollout SOPs, preview environments, and publishing docs.

Install

# In a process or artifact repo (devDependency, using pnpm — see below):
pnpm add -D @sequenceholdings/studio-cli @sequenceholdings/lattice

# Or globally:
pnpm add -g @sequenceholdings/studio-cli

Why pnpm and not npm

Sequence uses pnpm's minimumReleaseAge setting (in pnpm-workspace.yaml) as a 7-day supply-chain quarantine on new package releases. npm has no equivalent and would happily install a freshly-published malicious version of any transitive dep. External process repos scaffolded by seq-studio process init ship a pnpm-workspace.yaml with the same guard. Stick with pnpm so the policy actually applies. (The seq-studio publish chain — agent-spec, atlas-ui, lattice-form-renderer, artifact-studio, lattice, studio-cli — is excluded from the quarantine; those come from the Studio repo's own publish pipeline, so new seq-studio releases install immediately.)

Authenticate

Run the built-in browser login. seq-studio and seqapi share short-lived access tokens at ~/.config/sequence-api/tokens.json, so logging in with either CLI authenticates both. Refresh tokens are neither requested nor persisted; interactive commands perform a bounded PKCE login again after expiry.

seq-studio login                              # built-in Sequence environments
seq-studio envs add bsm-staging <tenant-url>  # one-time tenant registration
seq-studio login --env bsm-staging            # registered OpCo tenant realm
seq-studio doctor                             # confirms config + auth + authorization

Use seq-studio logout to remove the shared Sequence session, or seq-studio logout --env bsm-staging to remove only that OpCo realm's session.

Headless auth (CI) — M2M

When there's no interactive login (CI, automation), set the service-account secret and seq-studio mints a token via the Auth0 client-credentials grant. A valid cached user session wins over an ambient M2M secret (common under Doppler atlas/dev); force the service account with SEQAPI_AUTH_MODE=m2m:

export AUTH0_M2M_CLIENT_SECRET=...              # built-in Sequence environments
export AUTH0_M2M_CLIENT_SECRET_BSM_STAGING=...  # registered bsm-staging realm
export SEQAPI_AUTH_MODE=m2m                     # optional: ignore a leftover user session
seq-studio artifact deploy -e <env>

Registered OpCo environment names are upper-snaked in the variable suffix (bsm-staging → BSM_STAGING). Secrets are read at runtime — never commit them. M2M carries app access but no user identity / workspace membership, so it's blind to user-scoped/private resources.

Artifact commands do not accept bearer tokens through argv or environment. Use interactive login or the realm-specific M2M secret above.

Environments

The CLI ships with a single built-in environment, local (http://localhost:5001). The other environments your identity may target are discovered after you authenticate: the CLI calls the platform's environment-discovery endpoint and caches the result at ~/.config/lattice/environments.json.

seq-studio login            # or use the matching M2M secret described above
seq-studio envs refresh     # fetch the environments visible to your identity
seq-studio envs list        # show them (name, URL, source)

Discovery also happens lazily: the first time you pass an -e <env> that isn't cached yet, the CLI refreshes the catalog before failing. What you can see depends on who you are — unauthenticated installs get local only, and authenticated identities get the deployments they're entitled to. Visibility is not access control: every request is still authorized server-side.

You can add or override trusted environments yourself in ~/.config/lattice/config.toml (user entries win over discovered ones). Authenticated requests accept only HTTPS origins at seqholdings.com or its subdomains, plus HTTP loopback origins for local development. The CLI revalidates that exact origin immediately before attaching credentials and never follows authenticated redirects.

# Must come before any [env.*] table — TOML attaches bare keys to the
# preceding table, so a trailing default_env is silently ignored.
default_env = "local"

[env.local]
url = "http://localhost:5001"

[env.my-atlas]
url = "https://my-atlas.seqholdings.com"

Pass --env <name> (or -e <name>) on commands that talk to the platform.

default_env applies to process commands. artifact commands read config.toml only when --env is passed; with no --env they fall back to the artifact folder's .artifact-studio/config.json defaultEnv (set by artifact link / artifact env use).

App bundle commands

A single sequence.app.yml defines the deployable contents of an app: ORM namespaces, managed functions, typed agents, Lattice processes, Data Pipelines, and Artifact Studio UIs. Shared packages are declared separately as build inputs. Each primitive keeps its own runtime definition; the app manifest controls source locations, dependencies, and deployment selection.

Availability: App orchestration remains an internal workflow. Standalone primitives retain their documented public/Preview availability. This change does not make function-to-ORM service-account access a public runtime contract.

| Command | What it does | |---------|--------------| | seq-studio init <dir> --with <kinds> | Scaffold a version 2 app, root pnpm workspace, shared package, README, and selected primitives | | seq-studio add <kind> <name> [--depends-on <ids>] | Add any primitive, including additional ORM namespaces and UIs | | seq-studio add package <name> | Add a shared TypeScript package to the manifest and pnpm workspace | | seq-studio deploy -e <env> [--yes] [--only id1,id2] [--dry-run] | Validate and deploy the selected app graph, including prerequisites |

init accepts orm, function, agent, process, pipeline, and artifact as a comma-separated --with list or boolean flags (--agent --process). The first function defaults to hello (--function-name changes it). Agent, process, and pipeline folders use the app name. Pipelines default to transformation stages; --pipeline-type ingestion|transformation|serving selects another template.

seq-studio init loan-tools --with orm,function,agent,process,artifact
cd loan-tools
pnpm install
seq-studio orm generate orm/loan_tools
seq-studio orm diff orm/loan_tools
# Review and commit the generated migrations before deployment.
seq-studio login -e <env>
seq-studio deploy -e <env> --dry-run
seq-studio deploy -e <env> --yes

seq-studio add agent reviewer
seq-studio add process approvals --depends-on reviewer-agent
seq-studio add orm audit
pnpm install
seq-studio orm generate orm/audit
seq-studio orm diff orm/audit
# Review and commit orm/audit/migrations/.
seq-studio add artifact admin
seq-studio add package contracts
pnpm install
seq-studio deploy -e <env> --only approvals-process --yes

Creating a default GCS-backed platform git-service repo (seq-studio repos create without --git-backend walgit, or the Repositories UI) seeds it with a Sequence app README. A fresh clone with that seed README is a valid init . target. Init preserves its git remote and existing ignores, replaces the seed README, and refuses ordinary non-empty repositories. The initial UI stays at artifact/; additional UIs live under artifacts/<name>/.

One workspace, shared packages

Install once from the root and commit the generated pnpm-lock.yaml. The root pnpm-workspace.yaml lists the manifest's JavaScript primitives and shared packages, preserves the seven-day dependency age gate, and explicitly controls build scripts. Generated nested install configuration is consolidated at the root. CI should use pnpm install --frozen-lockfile.

Every new app includes packages/shared, named @<app-id>/shared, with ordinary workspace:* dependencies from its JavaScript primitives. Export common types, validation, and helpers from src/index.ts. Additional packages are registered with seq-studio add package <name>; add them to consumers with:

pnpm --filter @loan-tools/primitive-hello add '@loan-tools/contracts@workspace:*'

The app deployment prepares self-contained function and artifact sources from their declared workspace dependencies. Shared packages are not independently deployed resources. Shared source packages support JavaScript, TypeScript, and JSON; keep browser assets in the artifact and keep shared packages independent of primitive source directories. Shared registry dependency ranges must agree with their consumers. Custom function builds must provide their built main entry or set package.json seqStudio.source to an explicit source entry. File-relative runtime constructs whose meaning would change during function bundling fail preflight; use explicit file imports for bundled data.

Agent definitions compile to declarative data; imported helpers do not run at runtime. Lattice mapper closures cannot capture arbitrary shared executable code. Put shared runtime business logic in a managed function and reference that primitive from the workflow. For reuse between app repositories, publish versioned packages and depend on registry versions.

Workspace deployments outside local require the root lockfile. Staging keeps its registry resolutions and overrides; the existing Managed Functions registry policy still applies. A lockfile from an unsupported registry is reported and resolved again by the function service, just as in standalone function deploys.

Manifest and deployment behavior

schema_version: 2
app:
  id: loan-tools
  title: Loan Tools
studio:
  created_with: 0.1.27
  min_cli: 0.1.27
packages:
  - name: '@loan-tools/shared'
    path: packages/shared
primitives:
  - id: reviewer-agent
    kind: agent
    path: agents/reviewer
  - id: approvals-process
    kind: process
    path: processes/approvals
    depends_on: [reviewer-agent]
  - id: admin-ui
    kind: artifact
    path: artifacts/admin
    project_id: admin
    depends_on: [approvals-process]
deploy:
  on_error: stop

Version 2 topologically orders depends_on prerequisites. Optional deploy.order is a preference among ready primitives. --only includes the selected primitives' transitive prerequisites; use app primitive IDs, not agent/process runtime IDs. Agent and process entries may set only to select definitions from their source folder. Agent and pipeline entries may set target to select a deployment identity.

Before the first ORM deployment, and after changing its schema, run seq-studio orm generate <namespace-path> followed by seq-studio orm diff <namespace-path>. Review and commit the generated migration ledger. Init creates the namespace source; it does not create this reviewed baseline automatically. A namespace without migrations fails deployment preflight with instructions to run orm diff.

Before any deployment, version 2 validates and compiles the selected sources. --dry-run performs this preflight without deploying. Pipeline preflight reads the remote repository, validates its source, and pins the resolved commit, so a pipeline dry run needs network access and authentication. Other local primitive checks do not deploy resources. Official artifact deployments require the full app checkout to be clean on main, including shared packages and the app manifest; local deployments retain the local development path.

Pipeline entries require repo: pipelines/<name> and ref; they may specify target; their path is the local authoring directory. Commit and push pipeline source to the declared platform git-service release unit before deploying. The app reuses the existing pipeline release workflow and waits for completion. Use --approved-by <caller-sub> when the target requires recorded approval and --wait-timeout 2h to control polling. Pipeline deployment plants jobs; it does not run them. Removing a manifest entry never implicitly deletes a resource.

deploy.on_error defaults to stop. continue deploys independent primitives and skips dependents of failed/skipped prerequisites. The operation is not atomic: successful deployments remain if a later primitive fails. Version 2 records the plan and outcomes in .sequence/deployments/<encoded-env>.json, ignored by Git.

Existing version 1 manifests retain their explicit/kind ordering, exact --only selection, and plan-only dry run. Change schema_version to 2 to opt into the new dependency/preflight semantics, then declare shared packages and configure a root pnpm workspace if you want shared builds. Adding an agent, process, or pipeline to a version 1 app upgrades the manifest to version 2 and raises its minimum CLI version; it preserves existing package files and deployment-order preferences. Existing function/artifact/ORM additions retain version 1. There is no automatic migration of existing dependency files or lockfiles.

Agent commands

Typed agent repositories export one or more defineAgent(...) values from files named agent.ts. Definitions are compiled in a credential-scrubbed child process, validated with the published @sequenceholdings/agent-spec contract, normalized, and hashed before deployment. Apply creates or updates only the definitions in the bundle; it never implicitly deletes agents.

| Command | What it does | |---------|--------------| | seq-studio agents init <dir> | Scaffold a standalone typed agent repository | | seq-studio agents validate [--dir <dir>] [--target <APP_ENV>] [--only <id1,id2>] | Compile and validate locally, without API access | | seq-studio agents plan [--dir <dir>] [--only <id1,id2>] | Offline compile/hash plan | | seq-studio agents plan [--dir <dir>] -e <env> [--target <APP_ENV>] [--only <id1,id2>] | Diff creates, updates, and unchanged definitions against an environment | | seq-studio agents apply [--dir <dir>] -e <env> [--target <APP_ENV>] [--only <id1,id2>] [--yes] | Apply creates and updates after showing the plan | | seq-studio agents list -e <env> | List visible runtime agents | | seq-studio agents show <id> -e <env> | Show one runtime agent |

For validate, plan, and apply, --only accepts a comma-separated list of agent IDs after deployment-environment selection; every requested ID must be selected.

An optional deploy-manifest.json targets definitions by deployment identity:

{
  "schemaVersion": 1,
  "definitions": [
    {
      "id": "680000000000000000000001",
      "path": "support/agent.ts",
      "environments": ["local", "staging", "production"]
    }
  ]
}

Standalone workflow:

pnpm dlx @sequenceholdings/studio-cli agents init support-agent
cd support-agent
pnpm install
pnpm exec seq-studio agents validate
pnpm exec seq-studio agents plan
# Authenticate only when ready to inspect or apply an environment:
pnpm exec seq-studio login
pnpm exec seq-studio agents plan -e <env>
pnpm exec seq-studio agents apply -e <env>

Use --repo agents/<name> [--ref <ref>] or --git-url <url> instead of --dir to materialize reviewed source from the platform git service.

ORM commands

seq-studio orm authors and deploys governed ORM v2 namespaces: TypeScript table definitions, Drizzle-authored read-only views, and policies plus named GraphQL documents compiled into persisted operations. Import Drizzle query helpers from @sequenceholdings/orm/drizzle; managed view builders are compiled to canonical SQL before registration.

| Command | What it does | |---------|--------------| | seq-studio orm init <dir> | Scaffold one v2 namespace package (sequence.config.ts, schema/*.ts, graphql/**, and codegen config). | | seq-studio orm generate [dir] | Generate schema.graphql, operations.manifest.json, typePolicies.gen.ts, and consumer codegen when codegen.ts is present. | | seq-studio orm generate [dir] --migration-export [--check] | Export orm.migration.json after validating the committed ORM migration. Pipeline migration planning recompiles these declarative inputs. --check compares against the current source and operations without writing; use it in CI. | | seq-studio orm validate [dir] | Parse and compile the namespace, then verify its committed migration chain is current. | | seq-studio orm plan [dir] -e <env> | Compare the compiled namespace with registry state without applying database changes. | | seq-studio orm diff [dir] [--check] | Author the next committed migration, or verify the migration/snapshot chain offline for CI. | | seq-studio orm apply [dir] -e <env> | Author a migration if needed, register/apply the namespace, activate its operation set, publish roles/capabilities, and refresh generated outputs. | | seq-studio orm execute <operation> [dir] --variables-file <file> -e <env> | Execute one named persisted operation from operations.manifest.json with variables from a JSON object file, as the signed-in caller. | | seq-studio orm migrate-from-yaml <dir> | Convert a legacy YAML namespace to TypeScript authoring while preserving its committed migrations. |

Install the CLI and ORM package together:

pnpm add -g @sequenceholdings/[email protected] @sequenceholdings/[email protected]

The everyday loop is:

seq-studio orm init lending
cd lending
pnpm install

# Edit sequence.config.ts, schema/*.ts, and graphql/**/*.ts.
seq-studio orm generate .
seq-studio orm plan . -e local
seq-studio orm apply . -e local
seq-studio orm validate .

apply --dry-run rehearses a migration against a disposable branch copy of the target environment's data. apply --no-create is the CI guard that refuses to provision a missing namespace. Destructive DDL requires explicit --allow-destructive consent.

Preview: ORM v2 is a Preview workflow. The generated namespace package depends on @sequenceholdings/orm@^2.0.0; use the matching published major version and keep generated manifests and migrations committed with source.

Process commands

| Command | What it does | |---------|--------------| | seq-studio process init <dir> | Scaffold a process repo: package.json, sample process.ts, tsconfig.json | | seq-studio process lint [--dir <path>] [--offline] | Static checks (graph, return contracts, agent schema, timeouts, and JSONata syntax); --offline skips live agent-schema lookup | | seq-studio process plan [--dir <path>] -e <env> | Build bundle, diff against currently-active version | | seq-studio process apply [--dir <path>] -e <env> [--only <id1,id2>] | Build → register bundle → promote each process. --only promotes just the named process ids (the bundle still contains the whole root — registration is inert) | | seq-studio process apply --repo processes/<name> [--ref <r>] -e <env> [--only <id1,id2>] | Same as above, but materializes the source from a platform git-service repo. Pinned commit SHA is injected as bundle provenance. Requires ATLAS_GIT_PAT (or the target realm's M2M secret for CI) | | seq-studio process test [--dir <path>] -e <env> [--offline] | CI wrapper: lint + plan, non-zero exit on errors or BREAKING diffs; see the offline limitation below | | seq-studio process simulate <id> [--dir <path>] | Isolated child-process walk with stubbed runners and hardened JSONata data-flow mapper evaluation (offline) | | seq-studio process bundle build [--dir <path>] [-o file.json] | Build a bundle locally | | seq-studio process bundle pull <hash> [-e <env>] [-o file.json] | Fetch a stored bundle | | seq-studio process bundle inspect <bundle.json> | Show a saved bundle's summary | | seq-studio process bundle list [-e <env>] [--limit N] [--cursor <hash>] | List registered bundles (paginated; CLI auto-fetches all pages) | | seq-studio process bundle publish <hash or bundle.json> [-e <env>] | Register a local bundle (no promote) |

Use lint --offline for checks without live registry lookups. test --offline also skips agent-schema lookup and permits skipping the active-version diff when environment/auth is unavailable, but it still attempts that live diff and resolves subprocess versions when needed. It is not a guarantee of network-free execution.

JSONata mapper contracts

jsonata('…') expressions are serialized as *_expr data and run in a memory-bounded worker with a five-second deadline. $eval is disabled. $addBusinessHours(isoString, seconds) is the only registered host function and returns an ISO-8601 string.

| Mapper slot | $ input | Named bindings | Expected result | |-------------|-----------|----------------|-----------------| | input / human context projection | Context snapshot | — | Runner input; human projections return a context snapshot | | artifact_refs | Context snapshot | — | Artifact-reference array | | dueDate | Context snapshot | — | ISO date, epoch milliseconds, or null | | emailNotification template/reminder | Context snapshot | $info | { subject, body } | | advance_allowed | Context snapshot | — | Advance-allowed ACL; OpCo authoring is rejected pending dynamic-ACL hardening | | parallel fan_out | Context snapshot | — | Branch-item array | | parallel join | Context snapshot | $branches | Node output | | subprocess output | Context snapshot | $child | Node output | | managed-function output | Context snapshot | $response | Node output | | node or supervisor retry predicate | { name, message } | — | true to retry |

process lint parse-checks all of these slots. process simulate evaluates the data-flow slots used by its topology walk (input, fan_out, join, and subprocess output). It intentionally keeps runners stubbed and therefore does not evaluate managed-function output mappers, send email, or execute due-date, ACL, artifact-reference, or retry behavior.

Remote source for apply

apply can deploy a process from the platform git service instead of a local checkout:

seq-studio process apply --repo processes/my-process -e staging
seq-studio process apply --repo processes/my-process --ref v1.2.0 -e production

The source is materialized to a temp dir, dependencies are installed from the committed pnpm-lock.yaml (must be Chainguard-resolved), process definitions are discovered, the bundle is built with the pinned commit as provenance, and the temp tree is cleaned up — even on error. Only the processes namespace is accepted; other namespaces (artifacts, managed-functions) are rejected.

Auth: same as artifact deploy --repo — ATLAS_GIT_PAT for the smart-HTTP clone path, or the target realm's M2M secret for CI's JSON materialize path. Those credentials remain in the parent CLI and are not forwarded to dependency installation or process build tooling. Each install uses fresh temporary package-manager caches that are removed after the invocation.

This is ambient-credential isolation, not an OS security sandbox. Build workers still run as the caller's uid, so hostile source may inspect other same-uid processes or readable files on platforms that permit it (for example, Linux /proc). Build reviewed source only; use a dedicated ephemeral runner with no unrelated credentials when the source is not trusted.

Process discovery

Local process commands scan <id>/process.ts under the root selected by --dir, then LATTICE_PROCESSES_ROOT, then the current working directory, in that precedence order. Relative paths resolve from the current working directory. Each process.ts must export default defineProcess(...). apply --repo selects a remote source and cannot be combined with --dir.

my-processes/
  demo-process/
    process.ts
  loan-origination/
    process.ts

seq-studio process lint --dir my-processes --offline  # finds both processes

Managed Function commands

| Command | What it does | |---------|--------------| | seq-studio functions init <dir> | Scaffold one standalone TypeScript managed function | | seq-studio functions dev [--dir <dir>] [--port <port>] | Run a local HTTP server with Managed Function cache context | | seq-studio functions build [--dir <dir>] | Validate a local manifest, bundle, lockfile, and size | | seq-studio functions deploy --dir <dir> -e <env> | Preview secrets and deploy a local function | | seq-studio functions build --repo managed-functions/<name> [--path <dir>] -e <env> | Materialize and validate a function from the platform Git Service | | seq-studio functions deploy --repo managed-functions/<name> [--path <dir>] -e <env> | Materialize and deploy a function from the platform Git Service | | seq-studio functions limits [-e <env>] [--json] [--fn <slug>] | Inspect fleet, runtime, cache, and bundle defaults/caps; optionally inspect one function's effective runtime limits | | seq-studio functions invoke --fn <slug> -e <env> [--data <json> \| --data @<file> \| --stdin] | Invoke a deployed function and print its response body |

A normal function repo keeps managed-function.yml at its root and omits --path. A repo may also contain related, independently deployed functions:

functions/
  get-loan/
    managed-function.yml
    package.json
    pnpm-lock.yaml
    index.ts
  update-loan/
    managed-function.yml
    package.json
    pnpm-lock.yaml
    index.ts

Select exactly one function directory for each build or deploy:

seq-studio functions build --repo managed-functions/encompass \
  --path functions/get-loan -e staging
seq-studio functions deploy --repo managed-functions/encompass \
  --path functions/get-loan -e staging

Each selected directory is a self-contained function package. Functions in the same repo share Git review and commit provenance, but keep separate manifests, versions, runtime resources, secrets, and permissions. --path accepts only a canonical relative directory inside a remote repo; use --dir for local source.

Deploying to local Atlas

Start local Atlas, then use the same deployment workflow:

seq-studio functions deploy --dir ./my-function -e local
seq-studio functions invoke --dir ./my-function -e local --data '{"name":"Atlas"}'
seq-studio functions logs --dir ./my-function -e local
seq-studio functions delete --dir ./my-function -e local --yes

For a worktree, replace local with its environment from seq-studio envs list (for example local:my-worktree). Local Atlas builds the uploaded source and runs Google's Functions Framework in a supervised local Node process. It needs neither GCP provisioning credentials nor a Trigger/Temporal worker for these functions. Registry access is still required to install dependencies.

Create, deploy, promote, rollback, invoke, and delete use the normal Atlas permissions. Redeploy starts a new process before switching the active runtime; a failed replacement keeps the previous runtime. Deletion stops the process, releases its port, and removes the function's local source/build/runtime files. Version and invocation history remain in the development database. Shared managed secrets remain until you delete the secret itself.

Set development secret values through the usual secrets workflow. Values are stored in private local files, never fetched from staging. The function receives only its declared secret mounts and runtime configuration. Enabled caching uses bounded process-local memory; it resets on redeploy or restart. Local function logs are bounded and reset with Atlas. Cloud infrastructure metrics are unavailable.

Local functions belong to the checkout and development database that created them. Atlas will reject deployment/invocation/deletion of a copied cloud function or a function owned by another worktree. After Atlas restarts, pending operations resume and active function processes restart on first invocation. Children exit when their Atlas parent exits, including a parent crash.

The local process uses Atlas's Node installation. It does not emulate cloud IAM, VPC egress enforcement, autoscaling, CPU limits, or memory provisioning. Functions are trusted development code running as your OS user. Hosted Atlas continues to use GCP. MANAGED_FUNCTIONS_EXECUTION_BACKEND=gcp explicitly retains the cloud backend for a local development process.

seq-studio functions dev remains a standalone HTTP harness; use deploy -e local to exercise the function through Atlas.

Invoke payloads can be inline JSON, a JSON file prefixed with @, or stdin:

seq-studio functions invoke --fn my-function -e local --data '{"name":"Atlas"}'
seq-studio functions invoke --fn my-function -e local --data @request.json
cat request.json | seq-studio functions invoke --fn my-function -e local --stdin

The function response body is written to stdout so it can be piped to another command. HTTP status is written to stderr, along with an invocation ID when one is available. JSON responses are pretty-printed; other response bodies are preserved as text. A non-2xx function response exits nonzero after printing the body.

Scaling

seq-studio functions limits                          # installed CLI's bundled policy; offline
seq-studio functions limits -e staging               # policy enforced by the deployed server
seq-studio functions limits -e staging --fn get-loan --json

The catalog shares its definitions with manifest validation and server enforcement; it is not a separately maintained help table. Use -e for authoritative environment policy when CLI/server versions differ. A failed server lookup is an error, never a silent fallback to local defaults. --fn additionally reports stored runtime limits for that function, not measured live GCP configuration. Cache entries describe platform policy and defaults, not that function's selected cache configuration. Changing defaults or deployment caps does not rewrite existing functions' stored runtime settings; inspect those with --fn and redeploy to apply manifest changes.

Each environment supports at most 100 non-archived managed functions across all organizations. Registered functions count even before their first deploy; versions do not consume additional slots. At capacity, creating a new function fails. Delete an unused function to free a slot. Existing functions can still be invoked, redeployed, promoted, and rolled back.

Managed functions keep one warm instance by default. Set min_instances: 0 in managed-function.yml to scale to zero, or raise the floor when first-request latency matters:

limits:
  cpu: 1
  concurrency: 16
  min_instances: 1
  max_instances: 3

min_instances defaults to 1, cannot exceed max_instances, and incurs Cloud Run idle-instance charges while warm. max_instances defaults to 3 and must be between 2 and 10 so every function can autoscale horizontally.

CPU and concurrency are configurable per function in managed-function.yml:

• cpu: auto (default), 1, or 2 vCPUs. auto leaves allocation to the provider based on memory; it is not a measurement of a deployed function's CPU. Explicit fractional CPUs are not supported. Our platform requires at least 512 MiB (memory_mb: 512) when selecting two CPUs.
• concurrency: 1–80 simultaneous requests per instance, default 1. Values above 1 require an explicit CPU setting because provider-selected fractional CPUs cannot support concurrent requests.

The example permits up to 16 requests per instance, sharing that instance's CPU and memory. Three instances therefore provide capacity for up to 48 simultaneous requests, not 48 instances. CPU-bound JavaScript may not benefit from more CPUs without worker threads; I/O-heavy functions are better candidates for concurrency. Opting into concurrency requires handlers to keep request-specific state out of mutable globals. Redeploy with seq-studio functions deploy -e <env> to apply these settings; promote and rollback carry the selected version's settings.

invoke_rate_per_minute applies per function across all Atlas replicas in the environment, using Atlas's shared Redis. All callers and invocation sources share one fixed 60-second window, starting with the first attempt. Exceeding it returns 429 with Retry-After (seconds until the window expires). Rejected attempts do not extend the window. Redis unavailability returns 503 without executing the function; there is no per-process fallback, including when invoking through a local Atlas instance. The standalone functions dev handler server does not pass through Atlas and does not enforce this gateway quota. This is not a rolling-minute or durable spending quota: adjacent windows permit boundary bursts, and Redis key loss (restart or eviction) resets the window. It controls how many requests are admitted over time; concurrency controls how many execute simultaneously within an instance. Increasing concurrency does not raise the configured invocation rate limit.

Invocation IP allowlist

Declare the function-level source-IP restriction in managed-function.yml:

invocation:
  allowed_ip_ranges:
    - 203.0.113.0/24
    - 2001:db8::/48

seq-studio functions build validates IPv4/IPv6 addresses and CIDRs locally; Atlas performs authoritative normalization during upload. /0 ranges are rejected. Omitting invocation or declaring allowed_ip_ranges: [] means unrestricted source IPs.

The policy is part of the immutable function version. It becomes live atomically when that version activates, a failed deploy leaves the current policy unchanged, and promote or rollback restores the selected version's policy. The gateway checks a non-empty policy before invocation permissions.

Server-owned resource authorization

Some functions expose regulated external resources whose authorization must be enforced by Atlas rather than by author code. Those functions select a reviewed adapter in managed-function.yml:

authorization:
  version: 1
  adapter: encompass.loan-read-by-number

The adapter name is a closed platform registry. Authors cannot provide JSON pointers or custom filtering logic. seq-studio functions build rejects an unknown adapter, an adapter on an unregistered function, or a protected function whose required adapter is missing. The manifest declares only the server-owned adapter; authors cannot configure its runtime resource selection or policy.

Protected Encompass reads use closed, function-specific contracts:

• loan point/search and eFolder adapters authorize the human caller against Atlas's current loan policy, then bind the returned loan or child resource to that decision;
• encompass.loan-read-full and encompass.loan-fields-read preserve approved full-loan access while rejecting wrong-loan and unsolicited-field responses;
• encompass.global-metadata-read covers the registered field-schema and Encompass-settings reads with bounded, projected outputs and no loan lookup.

These adapters also require a clean, full Git commit on the active function version. Rollout flags are platform kill switches; FGA function or suite invoker remains the runtime access grant. Download and write functions are not members of these read adapters.

ORM data access

A function declares its ORM Data API reach in capabilities.data, grouped by namespace: tables it may read, v1 actions and ORM v2 persisted operations it may invoke, and whether raw read query is allowed. At invoke time the platform mints a short-lived data token scoped to exactly these refs — an operation is scoped as <namespace>/ops/<OperationName> (the GraphQL operation name from the namespace's graphql/ documents, case-sensitive), and anything undeclared is denied by the Data API. A function that reaches any namespace must also attach a top-level service_account:

service_account: lucky-svc
capabilities:
  data:
    lucky:
      tables: [lucky_draws]
      operations: [RollLuckyNumber]

Managed Secret commands

| Command | What it does | |---------|--------------| | seq-studio secrets create <NAME> -e <env> [--org <slug>] | Register an org-owned secret (no value) | | seq-studio secrets set <NAME> -e <env> [--org <slug>] [--from-file <path>] | Set the shared default (write-only; file is not echoed) | | seq-studio secrets list -e <env> | Secrets you can see (never values) |

--org targets a managed-scope org other than the login tenant and selects the intended same-named secret for set, attach, detach, versions, set-default, and pin; it is required when the name exists in multiple orgs. Tenant pipeline credentials must be created on that tenant's deployment: seq-studio secrets create NAME -e <tenant> --org <tenant>. Sequence-owned environments (local, staging, production) only accept --org sequence. The API requires Managed Functions Admin on that org.

Artifact commands

seq-studio artifact <sub> is the entry point for Artifact Studio. It runs the @sequenceholdings/artifact-studio library (its ./cli runCli export), routed through ~/.config/lattice/config.toml and the shared platform login.

| Command | Underlying runCli verb | |---------|--------------------------| | seq-studio artifact init <dir> [--template react-vite\|nextjs] | init <dir> — defaults to the existing React/Vite scaffold | | seq-studio artifact link [dir] -e <env> [--project <id>] | link [dir] --env <env> | | seq-studio artifact build [dir] [-e <env>] | React/HTML: local bundle. Next.js: asynchronous hosted preview build on Atlas; use pnpm build for local compilation. | | seq-studio artifact plan [dir] -e <env> | plan [dir] --env <env> | | seq-studio artifact deploy [dir] -e <env> [--skip-unchanged] [--no-create] [--project <id>] | deploy [dir] --env <env> — --skip-unchanged no-ops (before building) when the remote active deployment's sourceHash and CLI/atlas-ui peer versions already match; --no-create errors instead of creating a missing project; --project <id> targets a project directly when duplicate slugs make the lookup ambiguous (slug must still match the manifest) | | seq-studio artifact dev [dir] -e <env> [--link <pkgDir>[,<pkgDir>]] [--port <port>] | React/HTML: rebuild preview on changes. Next.js: local development server and owner-only Atlas tunnel; --port selects its loopback port. | | seq-studio artifact pull <project-id> -e <env> [--out <dir>] | pull <project-id> --env <env> [--out <dir>] | | seq-studio artifact list -e <env> | list --env <env> — projects visible on the environment (slug, id, active version, visibility) | | seq-studio artifact show <slug-or-id> -e <env> | show <slug-or-id> --env <env> — one project's detail incl. active deployment, git provenance, and (for newer deployments) the building artifact-studio / force-aliased atlas-ui versions | | seq-studio artifact promote <deployment-id> -e <env> | promote <deployment-id> --env <env> | | seq-studio artifact rollback <deployment-id> -e <env> | rollback <deployment-id> --env <env> |

pull writes the active deployment's source files (default out dir: ./<project-id>) and errors when the project has no active deployment. promote and rollback resolve the target project from the current directory's .artifact-studio/config.json — run them from the linked artifact folder (or run seq-studio artifact link first).

React/HTML active (official) deploys to deployed environments require main with a resolved git commit and a clean artifact source directory for both Git Service (--repo) and local sources. When a local source is nested in a larger checkout, dirty files outside that source directory are ignored with a warning. Deployments targeting local may use any branch, including dirty working trees. Feature branches, dirty artifact source trees, non-git sources, and detached checkouts that cannot be attributed to main are preview-only for deployed environments (seq-studio artifact dev / preview channel); promotion applies the same provenance check.

React/HTML CLI atlas-ui stamp (DES-254): builds force-alias @sequenceholdings/atlas-ui to the CLI's copy — not the artifact's declared semver. Deployments record cliVersion + atlasUiVersion. Contract: @sequenceholdings/artifact-studio → VERSION-PIN.md.

Studio CLI 0.1.36 carries Artifact Studio 0.2.7 with Atlas UI 3.3.0 pinned exactly. Ordinary builds use canonical, mode-aware tokens.css; new projects use matching editor dependencies. Before rebuilding an older artifact, migrate numbered black/white opacity utilities to semantic roles and check a preview in light and dark mode. Legacy stylesheet entry points remain temporary aliases; they do not restore retired utilities. Existing deployed bundles change only when rebuilt and activated.

Next.js applications (prerelease, opt-in Preview)

This implementation is not generally enabled; use only a reviewed prerelease provided for an explicitly enabled pilot. Package publication and environment rollout are separate release gates.

Next.js support requires a CLI/SDK release containing the Next.js scaffold and an environment whose platform team has enabled the runtime and completed its gateway/build/hosting setup. It is not enabled merely by upgrading the CLI. Application developers need Atlas access, Node 24, pnpm and Git; no GCP account, provider credentials or cloud devbox is required. Existing React/HTML projects keep their current runtime unless their authors explicitly migrate them.

seq-studio artifact init example-next-app --template nextjs
cd example-next-app
pnpm install
seq-studio artifact validate
pnpm type-check
pnpm build

The scaffold pins approved Next.js 16.3 and React 19 versions and uses schema-v2 artifact.bundle.yml. It owns its React/Next dependencies; the React/Vite platform aliases do not apply. Commit the generated pnpm-lock.yaml. pnpm dev provides a standalone loopback UI check; SDK access to Atlas requires the authorized development session below.

seq-studio envs list
seq-studio login --env <environment>
seq-studio artifact link --env <environment>
seq-studio artifact dev --env <environment>

The CLI starts Next.js with the supported Webpack development server on loopback and connects an authenticated outbound tunnel to Atlas. It prints the owner-only preview URL and opens it in an interactive terminal. Source stays on your computer. Fast Refresh handles compatible UI edits; Next.js also reloads server code and reports compiler errors. Ctrl+C stops the child process and revokes the session. A disconnected laptop has no live preview; use a hosted preview when someone else needs to review the app.

Development recovery behavior:

• Manifest/capability changes stop the session with a restart instruction so Atlas can authorize the new policy.
• Package/lockfile changes restart Next.js. Install changed dependencies with pnpm install; the CLI does not silently install them.
• --link <package-directory> (comma-separate several) rebuilds the linked package, refreshes its built output and restarts Next.js. Native Fast Refresh remains active for application edits; a package restart can reset state.
• Network reconnect obtains a fresh tunnel lease and does not replay requests. Unexpected local process crashes receive up to three consecutive restart attempts, then exit with an actionable error.

Configure explicit nonproduction resource bindings in Atlas before making SDK calls. Missing or revoked bindings fail rather than selecting production. Managed secrets stay in hosted runtimes: use mocks, your own test credentials or an existing governed function locally, and a hosted preview for secret-backed application code. Browser capabilities and server capabilities are separate manifest declarations. Never put a secret in build.public_env or NEXT_PUBLIC_*. Local execution runs as your OS user; Atlas does not sandbox your laptop's filesystem or arbitrary outbound connections.

For an immutable hosted preview, commit the source and connect its Git Service repository, then run:

seq-studio artifact build --repo <namespace>/<repository> --ref <branch> --env <environment>

artifact build . --env <environment> also accepts a committed local project with repository provenance for a hosted preview. It is not an offline build. The CLI waits for Atlas's operation and prints the deployment link. --out writes the completed operation/deployment receipt, not a JavaScript bundle. Ctrl+C stops waiting but does not cancel the remote build. Next.js does not support artifact dev --once; use the hosted build command instead.

Official releases fetch and verify source from the Git Service in the target Atlas environment. Push the reviewed clean main revision before deploying:

seq-studio artifact plan --repo <namespace>/<repository> --ref main --env <environment>
seq-studio artifact deploy --repo <namespace>/<repository> --ref main --env <environment>

The Next.js plan command validates local source/toolchain inputs and prints the proposed build; it does not currently perform a remote policy diff. Atlas checks permissions, bindings and policy when the build is submitted. A local image or an arbitrary remote repository is not accepted as official release evidence. --skip-unchanged does not apply static-bundle skip logic to Next.js builds.

Atlas builds the production server and browser assets, checks the candidate and activates the deployment. Review hosted behavior and configuration in Artifact Studio before release. The hosted application runs independently of your computer. Framework support is App Router on the approved Node profile; custom Next servers, Pages Router, Edge runtime and production WebSocket services are outside this Preview workflow.

Source for build / plan / deploy

These commands can inspect source from three locations. React/HTML builds use the local build/upload pipeline; Next.js uses the hosted workflow above, with Git Service verification required for an official release:

| Flag | Source | |------|--------| | (none) / [dir] | a local folder (default, unchanged) | | --repo <ns>/<name> | a repo in the platform Git Service, e.g. --repo artifacts/accounts | | --git-url <url> | a public, credential-free HTTPS git URL (cloned to a temp dir) |

For React/HTML, --ref <branch\|tag\|commit> selects the revision for build and plan (default: the repo's default branch). Active deploys to deployed environments require main; local active deploys scope dirty-file checks to the source directory and warn about unrelated changes elsewhere in the checkout. --env local accepts any local source ref. Other refs are preview-only for deployed environments. A remote source is materialized to a temp dir, built, and torn down; the target project is resolved from the source's artifact.bundle.yml project_id. The deployment records the resolved commit as its git_commit provenance. --repo needs -e <env> + a platform login. M2M/CI builds accept only platform-managed --repo sources; --git-url is interactive-only and rejects embedded credentials, query tokens, SSH/file URLs, and Git remote helpers. dev is local-only.

Artifact builds, dependency installs, process-definition imports, and local process simulations run in short-lived children with an allowlisted runtime environment and a synthetic home/config directory. Parent bearer tokens, Auth0 M2M secrets, Doppler tokens, cloud credentials, GitHub tokens, and user config files are not inherited. The platform Git Service clone path passes only its single scoped PAT to git through an ephemeral askpass helper. This is a credential-inheritance boundary, not an OS filesystem sandbox: child code still runs as the invoking user and must be treated as trusted to read files that it names explicitly outside the synthetic home.

Pull / clone / deploy — which path?

These three look similar but fetch different things:

| Command | What you get | |---------|--------------| | seq-studio artifact pull <project-id> | Active deployment source files for an Artifact Studio project (built bundle inputs), keyed by project UUID — not git history | | seq-studio repos clone <ns>/<name> | Repo source tree. With ATLAS_GIT_PAT, a real git clone via smart-HTTP; otherwise JSON-API materialize (no .git dir) | | seq-studio artifact deploy --repo <ns>/<name> | Build and deploy repository source; React/HTML builds locally, while Next.js uses Atlas's verified hosted build. |

Auth (git-service PATs)

Personal Access Tokens authenticate git clone / git push (Basic auth: any username, PAT as password). You do not need seqapi.

Everyone (recommended) — Atlas UI

1. Open Settings → Tokens in Atlas for your environment (<your-atlas-url>/settings/tokens — run seq-studio envs list for the URLs visible to your identity)
2. New token → scopes repo:read (add repo:write for push) → copy once Merge is a repository grant (Merge / Admin), not a PAT scope.
3. Export and clone:

export ATLAS_GIT_PAT=atlas_git_…
seq-studio repos clone <namespace>/<repo> -e <env>
# or: git clone https://git:$ATLAS_GIT_PAT@<your-atlas-host>/api/git-service/repos/<id>/git

You can also open Repositories → Access tokens / the clone popover’s Manage tokens link.

CLI mint (optional)

Requires Auth0 login. Same identity as the UI:

seq-studio login   # add --env <registered-opco-env> for a tenant realm
seq-studio auth pat create --name laptop --scopes repo:read,repo:write -e <env>
# optional: --expires 1d|7d|30d|90d|1y|never  (default 30d)
# optional: --store-credentials   # git credential approve for the env host

seq-studio auth pat list -e <env>
seq-studio auth pat revoke <id> -e <env> --yes

The raw token is printed once on create.

Repos commands

seq-studio repos <sub> manages repos in the platform Git Service over the JSON API — the same repos --repo <ns>/<name> sources build from.

| Command | What it does | |---------|--------------| | seq-studio repos list -e <env> [--namespace <slug>] [--mine] | repos visible on the environment (permission-filtered) | | seq-studio repos namespaces [create <slug>] -e <env> | list namespaces, or create one (creator becomes owner) | | seq-studio repos show <ns>/<name> -e <env> | detail: id, branches, clone URL; artifact project id when slug matches | | seq-studio repos create <ns>/<name> -e <env> [--default-branch <b>] [--git-backend gcs_isomorphic\|walgit] | create a repo (GCS default + seed README; walgit starts empty on main; needs namespace write) | | seq-studio repos clone <ns>/<name> \| --url <clone-url> \| --id <uuid> -e <env> [--ref <r>] [--output <dir>] [--force] [--full] | smart-HTTP git clone --depth 1 when ATLAS_GIT_PAT is set (--full fetches history; a commit SHA stays full). --url/--id need no seqapi. Otherwise JSON materialize + PAT hint. --out remains an alias for --output. | | seq-studio repos pull <ns>/<name> -e <env> [--ref <r>] [--out <dir>] [--force] | always materialize via JSON API (no .git dir); refuses a non-empty destination unless --force | | seq-studio repos delete <ns>/<name> -e <env> [--yes] | delete a repo — interactive confirm unless --yes | | seq-studio repos ci show <ns>/<name> -e <env> [--ref <r>] | preview CI checks discovered from the ref | | seq-studio repos ci require <ns>/<name> --check <name> -e <env> | reserved for requiring a named CI check; currently refuses to write until the sandboxed runner is live | | seq-studio repos ci import <ns>/<name> -e <env> [--ref <r>] | reserved for requiring every discovered check; currently refuses to write until the sandboxed runner is live |

show prints the smart-HTTP clone URL (…/repos/<id>/git). Basic auth: any username, PAT as password. Prefer repos clone over hand-rolling the tree API.

PR CI discovers ci/check from the first available lint, typecheck, or check script and ci/test from test. A .seq/ci.json takes precedence; its checks array can declare script/argv checks or be empty to opt out.

For example:

{ "checks": [
  { "phase": "check", "script": "lint" },
  { "phase": "test", "command": ["pnpm", "test"] }
] }

Each check needs phase (check or test) and exactly one of script or command; name is optional and otherwise defaults to ci/<phase> (-2, etc. for additional checks in that phase). Discovery alone never blocks a merge. Until the sandboxed executor is live, repos ci show is preview-only, Settings controls are disabled, and require/import refuse to write (discovery currently posts neutral check-runs). Once the executor is live, repo owners can opt in by requiring check names in Settings or with repos ci require/repos ci import.

Pipeline commands

seq-studio pipeline <sub> authors and validates Data Pipelines stage specs — the typed contracts (<name>.stage.yml) in either a dedicated Pipeline repo (pipelines/<domain>) or an app monorepo (apps/<app>). Validation logic lives in @sequenceholdings/pipeline-spec (an optional peer, like @sequenceholdings/orm); install it alongside the CLI to use this family.

| Command | What it does | |---------|--------------| | seq-studio pipeline init --type ingestion\|transformation\|serving <name> [--dir <dir>] | Scaffold <name>.stage.yml (commented per-kind template) plus a src/ Databricks-notebook entrypoint stub (begins with # Databricks notebook source; serving stages are declarative — no stub). Refuses to overwrite an existing spec | | seq-studio pipeline validate [dir] [--assets <file\|url>] [--orm-contracts <file\|url>] [--json] | Run the full offline spec gate: envelope + body validation, schema_ref resolution, and repo-level graph validation (reference resolution, single-writer, cycles, column subsets, serving projection checks). Auto-loads orm-contracts.json from the pipeline dir when present. Exit 0/1 | | seq-studio pipeline repin-orm [dir] -e <env> [--target <id>] [--dry-run] | Resolve the environment's pipeline target (or use --target when ambiguous), fetch its active ORM v2 contracts, verify those serving projections remain compatible, then update orm-contracts.json and their satisfies.content_hash pins. Refuses to write when compatibility fails | | seq-studio pipeline plan --repo <namespace>/<slug> --ref <sha\|branch> -e <env> [--target <id>] [--json] | Enqueue and poll a durable Pipeline plan (materialize → SDK/validateSpecGraph → compile → live-diff → provision findings). <namespace> is pipelines or apps. Fails closed listing every missing target binding (alert channels, workspace, Databricks source.credential) plus Data Sync edge-worker machine/operation/credEnvFamilies mismatches before registry writes. Does not run Databricks bundle validate (that is a Trigger deploy-path hard gate). Exit 1 on destructive findings (CI-safe). --json emits the completed stable plan envelope | | seq-studio pipeline deploy --repo <namespace>/<slug> --ref <sha\|branch> -e <env> [--target <id>] [--approved-by <sub>] [--allow-destructive <resource-key> ...] [--run-now] [--wait-timeout <duration>] [--no-wait] | Plan then enqueue deploy; Trigger runs bundle validate then bundle deploy against reviewed bytes. <namespace> is pipelines or apps. Default is plant-only (jobs are created, not run). --run-now runs in-unit producer roots after bundle deploy; serving refresh provisioning completes before producer trigger.after tasks can run. If a producer fails, the terminal status includes the remote Databricks task/event error when available. --allow-destructive is repeatable and must exactly name every deletion/recreation finding in the immutable plan; only authenticated @seqholdings.com users may authorize it; permission, ownership, schedule-drift, and provisioning blockers cannot be overridden. Polls to terminal unless --no-wait. Targets that require approval need --approved-by naming the authenticated caller. | | seq-studio pipeline status --deployment-id <id> -e <env> [--json] | Fetch the current remote deployment status without changing it. Use this public command to continue monitoring after local polling stops | | seq-studio pipeline adopt --stage <slug> --ref <sha\|branch> -e <env> [--target <id>] --native-id <id> --approved-by <you> [--resource-key <key>] [--kind job\|dlt_pipeline] [--old-source-removal-pr <url>] [--repo <namespace>/<slug>] | Bind a live Databricks job/pipeline into the stage without recreation (bundle deployment bind on Trigger). Always requires --approved-by naming the caller. When the key is still in the monorepo DAB, pass --old-source-removal-pr and follow the returned cutover checklist: unbind the old bundle state without deleting the remote, then remove its DAB declaration and add the target-specific adopted-resource entry in the same PR before redeploying. | | seq-studio pipeline unbind --stage <slug> --ref <sha\|branch> -e <env> [--target <id>] --approved-by <you> [--resource-key <key>] [--repo <namespace>/<slug>] | Release an adopted binding on Trigger; the remote object stays live (never deleted) | | seq-studio pipeline run-now --stage <slug> -e <env> [--target <id>] [--repo <namespace>/<slug>] [--json] | Run the stage's active job or DLT pipeline immediately and print its Databricks run URL | | seq-studio pipeline promote --stage <slug> --version <v> -e <env> [--target <id>] [--repo <namespace>/<slug>] [--approved-by <you>] [--wait-timeout <duration>] [--no-wait] | Promote a validated version to another target. Targets that require approval need --approved-by; --repo disambiguates a slug that exists in multiple Pipelines | | seq-studio pipeline rollback --stage <slug> -e <env> [--target <id>] [--repo <namespace>/<slug>] [--approved-by <you>] [--wait-timeout <duration>] [--no-wait] | Redeploy the previously retired deployment's version. Targets that require approval need --approved-by. |

-e/--env selects the Atlas connection. --target selects the logical pipeline target advertised by that endpoint. It is optional when the alias matches a target id or when the endpoint has exactly one target.

Unless --no-wait is set, plan, deploy, promote, and rollback report status or status-detail changes while waiting, then emit a 20-second progress heartbeat. Deploy, promote, and rollback wait up to 2 hours by default; pass --wait-timeout <duration> with a positive value such as 10m or 2h to override that local polling window. --no-wait only stops local polling—the remote deployment continues. If the wait window expires, output includes the deployment ID and an exact seq-studio pipeline status command for continued monitoring. Internal operators also receive the equivalent seqapi command; failures include the status detail, and any available Trigger run ID is shown. --json output is unchanged.

Coordinated schema migrations (Preview, staff access)

Ordinary plans include a report comparing deployed output declarations with physical Delta schemas and their Lakebase serving tables. Missing inventory and unsupported dependencies are reported explicitly. This report is advisory; ordinary deployment behavior remains unchanged.

Commit a versioned migrations/<id>.yml manifest, then add --migration <id> to pipeline plan to prepare its execution plan. The manifest declares participating pipeline repositories, column additions/type changes, stages that rebuild their complete writer scopes, and acceptance checks. Every participant ref resolves to an immutable commit. The assessment validates all proposed shared writers together.

For example, after changing both writers' Spark code and output declarations to produce decimal balances, the root repository can declare:

schema_version: 1
id: decimal-balances
participants:
  - { repo: pipelines/secondary-ledger, ref: main }
changes:
  - { stage: gold, output: gold.accounts, columns: [balance], kind: change_column_type }
  - { repo: pipelines/secondary-ledger, stage: gold, output: gold.accounts, columns: [balance], kind: change_column_type }
rebuild:
  - { stage: gold, mode: full_writer_scope }
  - { repo: pipelines/secondary-ledger, stage: gold, mode: full_writer_scope }
orm:
  - { repo: namespaces/finance, ref: main, path: '.', namespace: finance }
checks:
  - { kind: row_count, stage: gold, output: gold.accounts, comparison: equal }
  - { kind: orm_operation, namespace: finance, operation: VerifyAccounts }

The proposed output declarations define the desired types. Planning also checks the actual stored types against the deployed declarations. Business calculations stay in Spark; the migration specifies coordination and acceptance criteria. VerifyAccounts must be a persisted read operation in the pinned ORM export. Each changed shared writer must participate.

If an earlier output declaration was inaccurate, explicitly record the observed Delta type under baseline, for example:

baseline:
  - stage: gold
    output: gold.accounts
    columns:
      balance: decimal(18,2)

This allows that specific existing-column discrepancy only; the observation must match the native table, and unlisted drift still fails. The desired type still comes from the proposed output schema. A type already matching the desired type needs no schema conversion. Declared rebuilds and acceptance checks still run. This does not waive a mismatch in a Lakebase serving table or authorize dropping an undeclared column. Include each affected shared writer's baseline correction.

For an ORM participant, update the namespace source, run orm diff, then orm generate --migration-export, and commit the generated files with the source. Run orm generate --migration-export --check in CI to catch stale exports. Atlas reads the pinned JSON export and recompiles its schema and operations; it does not execute the repository's TypeScript. The export checksum detects inconsistent contents; the reviewed Git commit provides provenance.

Planning returns a migration run ID and immutable plan hash after checking native schemas, serving dependencies, participating releases and ORM consumers. It does not pause jobs or change native tables. Review that plan, then use its run ID and hash with the separate migration lifecycle:

seq-studio pipeline plan --repo pipelines/example --ref main --migration decimal-balances -e staging
seq-studio pipeline migrate start --run-id <run-id> --plan-hash <plan-hash> -e staging
seq-studio pipeline migrate status --run-id <run-id> -e staging
seq-studio pipeline migrate resume --run-id <run-id> --plan-hash <plan-hash> -e staging
seq-studio pipeline migrate cancel --run-id <run-id> --plan-hash <plan-hash> -e staging

The planning user must authorize start, resume and cancellation against the same target and hash. The API queues a durable worker; closing the CLI does not stop it. status --json includes phase progress, native operation IDs, worker state, retained reservations and validation results. A queued task is distinguished from a worker that has actually claimed the migration. Failed or unknown native work remains visible even when a parent task is retrying.

The worker pauses and drains the captured jobs, builds candidates with the pinned Spark code, runs declared acceptance checks, publishes validated Delta data, reconciles Snapshot copies and views, installs the new jobs while paused, and activates pipeline and ORM registry pointers together. New serving stages can attach to an existing producer job. Their new copies, physical identities, projections and public views are verified before activation. Original schedules resume only after consumer checks pass.

Before publication, cancellation stops candidate work and restores original schedules. After publication, it retains reservations and backups for forward recovery; it does not promise automatic rollback. Resume first reconciles the recorded native operations so a lost response does not duplicate completed work.

V1 supports