@sequenceholdings/studio-cli — seq-studio

Standalone CLI for the Sequence platform: Lattice processes, Artifact Studio apps, Managed Functions, Managed Secrets, and platform git repos. Runs from any repo against the platform over HTTP — no monorepo checkout required.

seq-studio process lint
seq-studio process plan -e <env>
seq-studio process apply -e <env>
seq-studio artifact deploy -e <env>
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) 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 — 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 once. seq-studio and seqapi share the resulting tokens at ~/.config/sequence-api/tokens.json, so logging in with either CLI authenticates both.

seq-studio login
seq-studio doctor   # confirms config + auth + authorization

Use seq-studio logout to remove the shared cached tokens.

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 (M2M wins when the secret is set, otherwise the cached user token is used):

export AUTH0_M2M_CLIENT_SECRET=...   # provided by your platform administrator
seq-studio artifact deploy -e <env>

The secret is read at runtime — never commit it. M2M carries app scopes but no user identity / workspace membership, so it's blind to user-scoped/private resources.

Manual escape hatch: any artifact command also accepts an explicit --token <jwt>, which wins over both the M2M and cached-user paths.

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: export AUTH0_M2M_CLIENT_SECRET=...
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 always add or override environments yourself in ~/.config/lattice/config.toml (user entries win over discovered ones):

# 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://atlas.example.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).

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 | Static checks (graph, return contracts, agent schema, timeouts) | | seq-studio process plan -e <env> | Build bundle, diff against currently-active version | | seq-studio process apply -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 AUTH0_M2M_CLIENT_SECRET for CI) | | seq-studio process test -e <env> | CI wrapper: lint + plan, non-zero exit on errors or BREAKING diffs | | seq-studio process simulate <id> | In-process walk with stubbed runners (offline) | | seq-studio process bundle build [-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) |

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 AUTH0_M2M_CLIENT_SECRET for CI's JSON materialize path.

Process discovery

seq-studio walks the current working directory for any subfolder containing a process.ts file. Each process.ts must export default defineProcess(...). Set LATTICE_PROCESSES_ROOT to point at a different folder.

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

cd my-processes
seq-studio process lint     # finds both processes

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 seqapi token.

| Command | Underlying runCli verb | |---------|--------------------------| | seq-studio artifact init <dir> | init <dir> | | seq-studio artifact link [dir] -e <env> [--project <id>] | link [dir] --env <env> | | seq-studio artifact build [dir] | build [dir] | | 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 already matches the local source; --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> | dev [dir] --env <env> | | 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 | | 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).

Source for build / plan / deploy

These three commands read their source tree from one of three places — the rest of the pipeline (build → upload) is identical regardless of origin:

| 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> | any git URL (cloned to a temp dir) |

--ref <branch\|tag\|commit> selects the revision (default: the repo's default branch). 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; --git-url needs git credentials for private repos. dev is local-only.

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 + deploy an artifact whose source lives in the platform git service (materializes, builds, uploads) |

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
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
seq-studio auth pat create --name laptop --scopes repo:read,repo:write -e <env>
# optional: --expires 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>] | create an empty repo (needs namespace write) | | seq-studio repos clone <ns>/<name> \| --url <clone-url> \| --id <uuid> [-e <env>] [--ref <r>] [--out <dir>] [--force] | smart-HTTP git clone when ATLAS_GIT_PAT is set (--url/--id need no seqapi); otherwise JSON materialize + PAT hint | | 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 |

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.

Authorization

The CLI carries no permissions of its own: every request is authorized server-side against your platform identity. Process apply and bundle registration require platform write access; managed functions, secrets, artifact projects, and repos are each gated by their own per-resource permissions. A 403 means your account lacks the grant for that resource — contact your platform administrator.

Design

seq-studio knows only the platform HTTP API, the seqapi token file, and config.toml. The server does the work — register the bundle, promote the version, write the audit log — so the CLI runs from any checkout without server-side wiring on the developer's machine.