Get started with Spex

Open Spex and a project

Follow the full Spex getting-started guide to install and open the IDE. Add a local project, or create a new project with its specs scaffold. In Settings → Agents, choose and save the Captain's adapter and model, follow its readiness instructions, and check the players your workflows use. Coding-agent sign-in is separate from Space sign-in.

Use the CLI

With Node.js 22 or later and npm, run these commands in your project directory:

npm install -g @sublang/spex
spex scaffold
spex lint
spex --help

Scaffolding creates specs/ and agent instructions, plus an Apache-2.0 LICENSE only if one is missing. To scaffold without a global install, use npx @sublang/spex scaffold.

Refresh templates with spex scaffold --update from a Git repository with a clean specs/ tree; review the diff, then run spex lint. See the full CLI guide for options and upgrades.

Attach to a local Spex server

For project and package commands, use CLI 4.1.0 or later with Spex App 0.9.0-beta.18 or later. From the app's source checkout, run npm run start:server and leave it running. In another terminal, set its private local access URL; keep it private because it grants access to the server's home. Scaffold and lint need no server.

export SPEX_SERVER_URL='<private local access URL printed by the server>'
spex project add /absolute/path/to/project
cd /absolute/path/to/project

Sign in only for private packages or publication:

spex auth login --instance https://cn.spex.sublang.ai
spex auth status

Follow the displayed sign-in instructions. Package commands select the registered project at your exact current directory; run from its root or pass --project /absolute/path/to/project. Replace example package names and folder paths with your own. Sign-in does not prove catalog reading or records Sync.

Commands report their own result. If a connection is lost or a wait times out after dispatch, the result is unknown and work may still complete. Inspect its state before retrying; the CLI never resends the operation.

Install and use a package

Public packages need no account to browse or install. In Playbooks, select your project's side, choose Add from registry, search, choose a version, then Add. Private packages never appear in search: sign in with access, choose Add by name, and enter the known org/name and a version or range, such as 1.2.3 or ^1.2.3. Check the environment for installation or an error.

Or use the attached CLI; add resolves, installs and exports, while install uses the existing lock:

spex package search toolkit
spex package add my-org/toolkit --version '^1.0.0'
spex package install
spex package status

Specs and skills are available through your native agent's skill discovery. For a playbook, find Not enabled, choose a player for every role, then Enable. Start a new task and type / to use its command. Installing alone does not enable a playbook.

Compile, enable and run custom playbooks in the IDE; the CLI installs and publishes their packages.

Publish your work

Publication requires signing in through Space to the publishing instance and a claimed org you can publish to. Manage claims in Your orgs; your personal namespace alone does not qualify. Choose Private on a new claim for private packages. The full guide explains how to create an eligible group if needed.

A spec or skill folder

Prepare a valid package folder inside your project. Choose Playbooks → Add from folder, enter its org/name and project-relative folder path, then Add. Select Publish on its local package row. No playbook or compilation is required.

A custom playbook

Choose New playbook, enter its id, org and license, and describe the workflow. Inspect Source, then Compile. On Enable, choose the command and players, enable it and try its command. Return to that tab and choose Publish.

For either path, review the destination instance, package name, version and upload files before confirming Publish. Only declared artifacts are uploaded, not your whole project.

Publish a folder from the CLI

With the same Space sign-in and claimed-org access, name a valid project-relative package folder. The dry run shows the actual destination, name, version and declared files without uploading. The explicit publish command uploads directly and reports its publication receipt:

spex package publish packages/toolkit --dry-run
spex package publish packages/toolkit

Optional: share project records

Choose the same instance as your team from the Groups page. Enter its address in the Space sign-in card; if you are already signed in, use Space → Add instance…. Signing in with another provider does not move your groups.

Package installation needs no records sync. If you share records through Space, read the sharing notice first: group members can see records, including session attachments.