Developer workflow
Bring Klayd into your repository.
The Klayd CLI connects the canonical component document to local code generation. IDEs and CI can call the same commands, keeping one predictable integration contract.
Open Developer tools from the project card you want to connect. Project-scoped access tokens keep each repository and automation separate from your browser session and from every other Klayd project.
Create project access
Go to Projects, open the … menu on the project card, and choose Developer tools. The panel contains the project ID, a repository quick start, and every token issued for that project.
- Name the integration
Use a recognizable name such as “Local development” or “Production CI”.
- Choose the minimum access
Read access covers pull, diff, validation, export, and review. Select write access only when an agent must apply reviewed snapshot changes.
- Create and copy the token
Klayd displays the complete token once. Store it in your environment or secret manager; tokens expire after 30 days and can be revoked from the same panel.
Connect a repository
export KLAYD_ACCESS_TOKEN='klayd_pat_…'
npm run klayd -- init --project project-id --framework react
npm run klayd -- pull
npm run klayd -- validate
npm run klayd -- exportThe generated klayd.config.json stores only project-safe settings. Access tokens remain in the environment and are never written into the repository. Return to the project's Developer tools panel to check whether a token is active, see when it was last used, or revoke it.
Command reference
| Command | Purpose |
|---|---|
init | Link a repository to a Klayd project and choose its default framework. |
status | Show the linked project, framework, local snapshot, and export destination. |
pull | Fetch the latest canonical component snapshot from Klayd. |
diff | Detect whether Design DNA or component documents changed remotely. |
validate | Validate the schema and framework compatibility before generation. |
export | Generate the complete framework package into the configured directory. |
review | Open the linked project directly in Visual Review. |
Use it from an IDE
Add the CLI commands as VS Code tasks or JetBrains run configurations. A thin editor extension can then surface status, validation, export, and Visual Review without owning a second copy of Klayd’s component logic.
{
"label": "Klayd: validate and export",
"type": "shell",
"command": "npm run klayd -- validate && npm run klayd -- export",
"group": "build",
"problemMatcher": []
}Agent-safe API behavior
Agent tokens are limited to one project and explicit scopes. Snapshot mutations run as a dry run by default, return a structured diff, and require the last observed revision before Klayd applies them.
PUT /api/agent/v1/projects/{projectId}/snapshot
Authorization: Bearer klayd_pat_…
{
"dryRun": true,
"expectedRevision": "sha256 revision from the latest read",
"snapshot": { "snapshotSchema": "klayd.editor-snapshot", "…": "…" }
}Agents can discover the current contract at /api/agent/v1/capabilities before reading a project. This exposes the API version, schema version, supported frameworks, scopes, and mutation safeguards without requiring authentication.
CI workflow
- Pull and compare
Run diff to detect a newer canonical project snapshot.
- Validate before generation
Fail early on schema corruption or framework-incompatible components.
- Generate deterministic files
Export from the same component documents reviewed in Klayd.
- Review the visual result
Attach the linked Visual Review URL to the pull request.