# Activates a User on an Environment.
Source: https://docs.versori.com/api-reference/platform-api/end_users/activates-a-user-on-an-environment
/openapi/platform-api.yaml post /o/{organisation_id}/activations
ActivateUser activates a user on an environment. This will create a new activation record for the user on the environment.
Connections must be made for all environment systems to be successfully activated.
# Create an End User
Source: https://docs.versori.com/api-reference/platform-api/end_users/create-an-end-user
/openapi/platform-api.yaml post /o/{organisation_id}/users
CreateEndUser creates a new End User for the given organisation.
The end user requires a unique `externalId`. This is an immutable field so should not be set to something that may change
such as an email address.
# Delete an End User
Source: https://docs.versori.com/api-reference/platform-api/end_users/delete-an-end-user
/openapi/platform-api.yaml delete /o/{organisation_id}/users/{user_id}
DeleteEndUser deletes the End User for the given user ID.
# List End Users
Source: https://docs.versori.com/api-reference/platform-api/end_users/list-end-users
/openapi/platform-api.yaml get /o/{organisation_id}/users
ListEndUsers returns a list of all the End Users for the given organisation.
# Retrieve an End User
Source: https://docs.versori.com/api-reference/platform-api/end_users/retrieve-an-end-user
/openapi/platform-api.yaml get /o/{organisation_id}/users/{user_id}
GetEndUser returns the End User for the given user ID.
# List available execution pools.
Source: https://docs.versori.com/api-reference/platform-api/execution_pools/list-available-execution-pools
/openapi/platform-api.yaml get /o/{organisation_id}/execution-pools
# Clone Environment
Source: https://docs.versori.com/api-reference/platform-api/projects/clone-environment
/openapi/platform-api.yaml post /o/{organisation_id}/projects/{project_id}/environments/clone
CloneEnvironment creates a new environment by copying the details of an existing environment in the same project.
# Clone Project
Source: https://docs.versori.com/api-reference/platform-api/projects/clone-project
/openapi/platform-api.yaml post /o/{organisation_id}/projects/{project_id}/clone
CloneProject clones the project with the given ID. The new project will have a new ID and will not be deployed.
The files and configuration will be copied from the original project. Connection templates will be copied, however
no connections will be created.
# Create new project
Source: https://docs.versori.com/api-reference/platform-api/projects/create-new-project
/openapi/platform-api.yaml post /o/{organisation_id}/projects
CreateProject creates a new project.
# Delete Project
Source: https://docs.versori.com/api-reference/platform-api/projects/delete-project
/openapi/platform-api.yaml delete /o/{organisation_id}/projects/{project_id}
DeleteProject delete the project.
# Get Project
Source: https://docs.versori.com/api-reference/platform-api/projects/get-project
/openapi/platform-api.yaml get /o/{organisation_id}/projects/{project_id}
GetProject returns the files and configuration for the specified project ID. If one does not exist then a 404 will be returned.
# List projects for organisation
Source: https://docs.versori.com/api-reference/platform-api/projects/list-projects-for-organisation
/openapi/platform-api.yaml get /o/{organisation_id}/projects
# Sync Environments
Source: https://docs.versori.com/api-reference/platform-api/projects/sync-environments
/openapi/platform-api.yaml post /o/{organisation_id}/projects/{project_id}/environments/sync
SyncEnvironments copies the deployment configuration (currently the deployed docker image/version) from one
environment to another within the same project.
# Update Project
Source: https://docs.versori.com/api-reference/platform-api/projects/update-project
/openapi/platform-api.yaml put /o/{organisation_id}/projects/{project_id}
UpdateProject updates the project record. This endpoint will not make changes to the file or the running deployment.
# Installation
Source: https://docs.versori.com/latest/ai-tooling/installation
Add the Versori skill to Cursor, Codex, Claude Code, or any other AI coding tool.
## Prerequisites
Before adding the skill, ensure you have:
1. The [Versori CLI installed](/latest/cli/installation)
2. An authenticated CLI context — see the [Quickstart](/latest/cli/quickstart) guide
The Versori skill is bundled with the CLI. You can either download it into any AI tool's skill directory, or install it as a plugin in Claude Code.
## Any AI tool
The skill can be used with any AI tool that supports skill or agent files, such as Cursor, Codex, and Claude Code.
Use the CLI to extract the skill to your tool's skill directory. For example, for Cursor:
```sh theme={null}
versori skills download --directory ~/.cursor/skills/
```
Point `--directory` at wherever your tool loads skills from.
If your tool works better with a single file — for example Codex or Cursor using `AGENTS.md` — use the `--agent` flag to combine the skill into an `AGENTS.md` file:
```sh theme={null}
versori skills download --agent --directory ./
```
To download the latest skill from GitHub instead of using the bundled version:
```sh theme={null}
versori skills download --latest --directory ~/.cursor/skills/
```
Describe your integration task to your AI tool. The skill will guide it through the full workflow — from research through deployment.
```
Build an integration that syncs new Shopify orders to QuickBooks as sales receipts.
```
## Claude Code plugin
If you use Claude Code, you can install the skill as a plugin in one step instead of downloading it manually.
The plugin marketplace below is Claude Code's own, and it installs the Versori skill into your local editor.
It is a different thing from the [Versori skills marketplace](/latest/ai-tooling/marketplace), which adds
skills to your Versori organisation for the AI that plans and builds your integrations.
In Claude Code, add the Versori plugin marketplace:
```
/plugin marketplace add versori/cli
```
Then install the skill plugin:
```
/plugin install versori-skills@versori-cli
```
After installation, the plugin activates automatically when Claude Code detects integration-related tasks. You can verify it is installed by checking your active plugins:
```
/plugins
```
You should see `versori-skills@versori-cli` listed with its `coding-versori-sdk` skill.
See the [`versori skills` command reference](/latest/cli/commands/skills) for the full list of flags and options.
# Manage Your Skills
Source: https://docs.versori.com/latest/ai-tooling/manage-skills
Upload your own skills to your Versori organisation, then edit them, set whether they always apply, and remove them.
Your organisation's skills live on the **Skills** page, reached from the left-hand navigation. It lists everything
the AI can draw on, both the skills you have uploaded and the skills you have added from the
[marketplace](/latest/ai-tooling/marketplace), with a count of the total.
Two buttons sit in the header:
* **Upload skill**: add a skill your team has written
* **Browse marketplace**: add a ready-made skill from the Versori catalogue
To find a skill in a long list:
* **Search skills** matches on name and summary
* **Status** shows only **Mandatory** or **Optional** skills
* **All categories** filters by category, offering only the categories your own skills use
* **Sort** orders the list by **Name A-Z**, **Name Z-A**, or **Recently updated**
Select any skill to open it and read its `SKILL.md` and resource files.
## Upload a skill
Create a `SKILL.md` file with the [frontmatter and guidelines](/latest/ai-tooling/skills#the-skillmd-file)
you want the AI to follow. Add resource files alongside it if your guidelines reference longer material.
On the **Skills** page, select **Upload skill**, then drop in your skill or use **Select file** /
**Select folder**. Three shapes work:
* A `.skill` or `.zip` bundle
* A single `SKILL.md`
* A folder with `SKILL.md` at its root
Resource files may be `.md`, `.txt`, `.json`, `.yaml`, `.csv`, `.xml`, or `.html`. Anything else is
dropped from the upload, and the dialog tells you what it removed.
The index file must be named exactly `SKILL.md`. A miscased name such as `skill.md` is rejected, so a
bundle is never uploaded without its index.
**Name** and the skill body are read from your `SKILL.md` frontmatter. Fill in the rest as needed:
* **Summary**: one or two lines on what the skill does
* **Category**: an optional grouping label, used for filtering
* **Product image URL**: an optional logo shown against the skill
* **Mandatory**: turn on to apply this skill to every request. Leave it off unless you have a reason,
and see [How the AI applies skills](/latest/ai-tooling/skills#how-the-ai-applies-skills) first. You can
change it later from the skill's card.
The skill appears in your organisation's list, ready for the AI to use.
Uploads are checked for content that would try to hijack the AI's instructions, and an upload that fails the
check is rejected. If the check cannot run, the upload is refused rather than allowed through, so try again
shortly. Each file must be under roughly 200 KB, and a whole bundle under roughly 2 MB.
Skill names are unique within your organisation. Uploading a skill whose name is already taken is rejected as a
conflict. To change a skill you already have, edit it rather than re-uploading.
## Edit a skill
Open a skill you own and edit its `SKILL.md` or any resource file, then save. Each save records a new version, and
the AI picks up your change on its next request.
Skills added from the marketplace are read-only, because Versori maintains them. To change one, fork it first.
See [Fork a skill to customise it](/latest/ai-tooling/marketplace#fork-a-skill-to-customise-it).
## Mandatory and optional skills
Every skill carries a **Mandatory** or **Optional** badge, which decides how it reaches the AI. Optional is the
default: the AI reads the skill only when its description matches the work in hand. Mandatory puts the whole skill
into every request. See [How the AI applies skills](/latest/ai-tooling/skills#how-the-ai-applies-skills) for which
to choose.
Switch a skill between the two from its card, using **Make mandatory** or **Make optional**. The change applies to
your whole organisation and takes effect on the AI's next request.
Making a skill mandatory is a quick way to test whether the AI is missing it. If the results change once the
skill is always in context, the skill was relevant but its `description` was not specific enough for the AI to
find it. Sharpening the description is usually better than leaving it mandatory.
## Remove a skill
Each skill's card carries the removal action. What it does depends on where the skill came from:
| Skill | Action | Effect |
| -------------------------- | ------------- | -------------------------------------------------------------------- |
| Uploaded or forked by you | **Delete** | Removes the skill and its edits. This cannot be undone. |
| Added from the marketplace | **Uninstall** | Removes it from your organisation. You can add it again at any time. |
The confirmation dialog names the skill and which of the two is about to happen, so check it before confirming.
## Related docs
* [Skills](/latest/ai-tooling/skills): what a skill is and how the AI applies it
* [Skills Marketplace](/latest/ai-tooling/marketplace): add ready-made skills from the Versori catalogue
# Skills Marketplace
Source: https://docs.versori.com/latest/ai-tooling/marketplace
Browse the Versori skills catalogue, add skills to your organisation, and fork them to fit how your team works.
The skills marketplace is a catalogue of ready-made [skills](/latest/ai-tooling/skills) maintained by Versori.
Instead of writing a skill from scratch, you can add one to your organisation in a couple of clicks. If it is
close but not quite right, fork it and edit your own copy.
This is not the same thing as the Claude Code plugin marketplace. That one installs the Versori skill into your
local AI coding tool. See [Installation](/latest/ai-tooling/installation). The skills marketplace on this page
adds skills to your Versori organisation, for the AI that plans and builds your integrations.
## Browse the catalogue
Open **Skills** in the left-hand navigation, then select **Browse marketplace**.
Each skill shows its name, a short summary, and a category. To narrow the list:
* **Search marketplace**: match against skill names and summaries
* **Category**: filter to a single area, such as a particular product or partner
* **Sort**: order by **Featured**, **Name A-Z**, **Name Z-A**, or **Recently updated**
Select any skill to read its full `SKILL.md` and resource files before you commit to adding it.
## Add a skill to your organisation
In **Browse marketplace**, select the skill you want. Its contents open so you can review what the AI will
be told to follow.
The button changes to **Added** once it succeeds, and the skill appears in your organisation's skill list
tagged **Installed**.
Adding a skill applies it to your whole organisation, so every integration the AI plans or builds can use it. There
is no per-integration step.
## Fork a skill to customise it
Marketplace skills are read-only: Versori maintains them, so you cannot edit one in place. To change one, **fork**
it. This creates an editable copy owned by your organisation, tagged **Forked from marketplace**.
Fork from the skill itself, or select several skills in your list and fork them together.
Open the forked skill and edit its `SKILL.md` or resource files. Your changes affect only your
organisation.
A fork is a point-in-time copy. If Versori later improves the original, your fork does not pick up the change,
so you would need to fork again. Prefer adding the marketplace skill as-is where you can.
## Mandatory or optional
A skill you have added is **Optional** by default, meaning the AI reads it when its description matches the work in
hand. Make it **Mandatory** to put it into every request instead. This is your organisation's choice about a skill
it has added, not something the catalogue sets. See
[Mandatory and optional skills](/latest/ai-tooling/manage-skills#mandatory-and-optional-skills).
## Remove a skill
Select **Uninstall** on the skill's card in your organisation's list. This removes it from your organisation, and
you can add it again from the marketplace at any time.
Forked and uploaded skills are yours rather than the catalogue's, so removing one **deletes** it and its edits.
The confirmation dialog tells you which of the two is about to happen.
## When the AI suggests a skill
The AI also searches the marketplace itself. If it finds a skill relevant to what you are working on, whether you are
planning an integration or partway through building one, it pauses and shows you a card naming the skill and why
it would help.
Choose **Install** to add it and carry on, or **Not now** to continue without it. Nothing is added unless you
select **Install**: because a skill changes how the AI behaves across your whole organisation, this is always your
decision rather than the AI's.
## Related docs
* [Skills](/latest/ai-tooling/skills): what a skill is and how the AI applies it
* [Manage Your Skills](/latest/ai-tooling/manage-skills): upload and maintain your own skills
* [Installation](/latest/ai-tooling/installation): the Claude Code plugin marketplace, for local AI coding tools
# AI-Assisted Integration Development
Source: https://docs.versori.com/latest/ai-tooling/overview
Use the Versori skill in your AI coding tool to build data integrations locally.
Versori ships a built-in skill, `coding-versori-sdk`, that turns your AI coding tool into a Versori integration expert. It guides the agent through the full integration lifecycle — from research and system setup through code generation, testing, and deployment.
The skill works with any AI coding tool that supports skills or agent files, including [Cursor](https://cursor.com/), [Codex](https://openai.com/codex/), and [Claude Code](https://www.anthropic.com/claude-code). When you describe an integration task, the skill provides your agent with structured knowledge about the Versori CLI, Run SDK, and platform workflow. It activates automatically when you work on ETL pipelines, API integrations, data synchronisation, webhooks, or mention Versori.
Add the skill to Cursor, Codex, Claude Code, or any other AI coding tool.
The structured 8-step process the skill follows to build integrations.
Get the most out of AI-assisted integration development.
Learn about the SDK used to build integration workflows.
## What the skill does
The skill equips your AI tool with knowledge of Versori's platform, CLI commands, and SDK patterns. When activated, it follows a structured workflow to:
* **Research** your integration requirements and produce a structured plan
* **Set up systems** on the Versori platform using the CLI
* **Create connections** with the correct authentication for each system
* **Generate TypeScript workflows** using the Versori Run SDK
* **Write and run tests** to validate your integration logic
* **Deploy** the finished integration via the CLI
## Prerequisites
Before using the skill, make sure you have:
* A [Versori account](https://platform.versori.com) with an active organisation
* The [Versori CLI installed](/latest/cli/installation) and [authenticated](/latest/cli/quickstart)
* [Node.js](https://nodejs.org/) or [Deno](https://deno.com/) installed for local development and testing
* An AI coding tool such as Cursor, Codex, or Claude Code
The skill is distributed with the Versori CLI. Run `versori skills download` to add it to any AI tool, or install
the Claude Code plugin for a one-step setup. See the [Installation](/latest/ai-tooling/installation) page for details.
This page is about writing integration code locally with an AI coding tool. For the skills your organisation
gives to the AI on the Versori platform, see [Skills](/latest/ai-tooling/skills) and the
[Skills Marketplace](/latest/ai-tooling/marketplace).
# Skills
Source: https://docs.versori.com/latest/ai-tooling/skills
What Skills are in the Versori platform, how to write one, and how the AI applies them when planning and building integrations.
Skills are reusable sets of guidelines and best practices that teach the Versori AI how your team builds
integrations: coding standards, naming conventions, security requirements, or partner-specific rules. You add a
skill to your organisation once, and the AI follows it while planning, building, and reviewing.
Skills follow an open standard for packaging AI agent knowledge, so the same skill format works across the Versori
platform and AI coding tools such as Claude Code and Cursor.
Skills belong to an organisation, not to an individual integration. Open **Skills** in the left-hand navigation
to see everything your organisation has.
There are two ways to add one:
Add a ready-made skill from the Versori catalogue.
Upload a skill your team has written.
## What a skill contains
A skill is a small bundle of Markdown files:
| File | Required | Purpose |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SKILL.md` | Yes | The index file. Holds the skill's frontmatter and the guidelines the AI should follow. Must be named exactly `SKILL.md` (uppercase). |
| Resource files | No | Supporting files the `SKILL.md` can reference: for example, longer references, examples, or templates. Stored under their relative path (e.g. `references/naming.md`). |
## The `SKILL.md` file
`SKILL.md` begins with a YAML frontmatter block followed by the guidelines themselves, written in Markdown.
```markdown SKILL.md theme={null}
---
name: example-skill-name
description: One line describing what this skill covers and when the AI should apply it
---
# Criteria
- Replace this example with the rules or guidelines the AI should follow.
```
The frontmatter defines how the skill is identified and applied:
A short, unique name for the skill, shown in your organisation's skill list.
One line describing what the skill covers and when the AI should apply it. The AI uses this to decide whether
the skill is relevant to the work in front of it, so make it specific.
## How the AI applies skills
Adding a skill to your organisation is what makes it available: there is no separate step to attach it to a
project or an integration. Every skill on your **Skills** page can be used by the AI.
What differs is *how* each one reaches the model. Every skill is either **Optional** or **Mandatory**, shown as a
badge on its card:
The default. The AI sees the skill's name and `description`, and reads the full skill only when the
description matches the work it is doing.
The skill's full contents go into every request, whether or not the AI judges it relevant.
This is a choice your organisation makes about a skill it has added, not something the skill's author sets in the
file. Switch between the two at any time with **Make mandatory** and **Make optional**. See
[Mandatory and optional skills](/latest/ai-tooling/manage-skills#mandatory-and-optional-skills).
Prefer **Optional**. A clear, specific `description` is usually enough for the AI to find a skill at the right
moment, and it leaves more room for your own project's context. Reserve **Mandatory** for rules that must never be
missed, such as compliance requirements, and keep those skills short.
Some skills are built into the platform and always available. They are not listed alongside your organisation's
skills, and cannot be edited or removed.
## Related docs
* [Skills Marketplace](/latest/ai-tooling/marketplace): add a ready-made skill from the Versori catalogue
* [Manage Your Skills](/latest/ai-tooling/manage-skills): upload, update, and remove your own skills
* [Versori Skill](/latest/ai-tooling/versori-skill): the built-in `coding-versori-sdk` skill that ships with the CLI
* [Plan agent](/latest/how-it-works/plan): how Versori plans integrations
# Tips & Best Practices
Source: https://docs.versori.com/latest/ai-tooling/tips
Get the most out of AI-assisted integration development with the Versori skill.
## Prepare a research document
The skill works best when your AI tool has a clear understanding of the systems and requirements involved. Before starting, gather:
* **API documentation links** for each system you want to integrate
* **Authentication details** — which auth method each system uses (API key, OAuth 2.0, etc.)
* **Data models** — the objects and fields you need to map between systems
* **Example payloads** — sample API requests and responses help the agent generate accurate transformations
* **Trigger requirements** — whether the integration should run on webhook events, a schedule, or manually
Start your prompt with a research document or a detailed description of the integration. The more context you
provide upfront, the fewer iterations you will need.
## Write effective prompts
Be specific about what you want to build. A good prompt includes:
* **The systems involved** — name the source and target platforms
* **The trigger type** — webhook, schedule (with cron expression), or manual
* **Field mappings** — which fields in the source map to which fields in the target
* **Authentication methods** — how each system should authenticate
* **Edge cases** — what should happen when records already exist, when fields are missing, or when API calls fail
**Good prompt:**
```
Build an integration between HubSpot and Salesforce.
When a new contact is created in HubSpot (webhook), check if they exist in Salesforce by email.
If they exist, update the record. If not, create a new lead.
Use OAuth 2.0 for both systems.
Map: HubSpot firstname → Salesforce FirstName, HubSpot lastname → Salesforce LastName,
HubSpot email → Salesforce Email, HubSpot company → Salesforce Company.
```
**Vague prompt:**
```
Sync contacts between HubSpot and Salesforce.
```
The vague prompt will still work, but the agent will need to make assumptions about trigger type, field mappings, and authentication — leading to more back-and-forth.
## SDK patterns the skill uses
The skill generates code using the Versori Run SDK. Understanding these patterns helps you review and refine the generated workflows:
* **[Workflows & triggers](/latest/run-sdk/latest/workflows)** — webhook and schedule-based entry points for integrations
* **[Task types](/latest/run-sdk/latest/workflows/task-types)** — the building blocks of workflows: functions, HTTP calls, and more
* **[Context & KV storage](/latest/run-sdk/latest/context)** — how workflows access connections, logging, and persistent state
* **[Durable workflows](/latest/run-sdk/latest/durable-workflows)** — long-running workflows with persistent state across executions
## Common integration patterns
The skill handles a variety of integration patterns. These guides cover common use cases in detail:
* [Real-time integrations](/latest/guides/use-cases/real-time) — event-driven workflows triggered by webhooks
* [Batch integrations](/latest/guides/use-cases/batch) — scheduled data synchronisation between systems
* [Bidirectional sync](/latest/guides/use-cases/bidirectional) — two-way data flow between systems
* [Multi-tenancy](/latest/guides/use-cases/multi-tenancy) — integrations that support multiple end users
Always review generated code before deploying to production. While the skill follows best practices and
generates tested code, you should verify that field mappings, authentication configuration, and error handling
meet your specific requirements.
## Troubleshooting
If the skill is not activating or behaving as expected:
* **Check the CLI is authenticated** — run `versori context list` to verify you have an active context
* **Ensure a project exists** — the agent will guide you through creating one, but you can also create one manually with `versori projects create`
* **Check your prompt** — the skill activates on integration-related tasks. If your request is about something unrelated, it will not engage
* **Make sure the skill is installed** — confirm it is in your tool's skill directory, or re-run `versori skills download --latest` to get the latest version
# Versori Skill
Source: https://docs.versori.com/latest/ai-tooling/versori-skill
What the coding-versori-sdk skill contains, how it is structured, and the platform behaviour it encodes.
Versori ships a single built-in skill, `coding-versori-sdk`, that teaches an AI coding tool how to build data integrations the way the Versori platform expects. It turns any compatible AI tool — such as Claude Code or Cursor — into a Versori integration expert that follows the same lifecycle the platform uses internally.
This skill is delivered through the [Versori CLI](/latest/cli/installation) and the [Claude Code plugin](/latest/ai-tooling/overview). It runs in your local AI coding tool, so it is separate from your organisation's skills on the Versori platform: it does not appear on the **Skills** page, and it is not in the [skills marketplace](/latest/ai-tooling/marketplace). For Skills as a platform concept, including how to author and apply your own, see [Skills](/latest/ai-tooling/skills).
## What it provides
Rather than relying on whatever an AI model happens to know about Versori, the skill gives the agent authoritative, version-matched instructions. It teaches the agent how to:
* Recognise when a task is a Versori data-integration task
* Research source and target systems before writing code
* Set up systems and authenticated connections using the CLI
* Generate TypeScript workflows with the [Run SDK](/latest/run-sdk/latest/introduction) following platform conventions
* Write and run tests for transformation logic
* Verify and deploy integrations safely
## What it covers
The skill spans the full integration lifecycle:
* TypeScript workflow authoring with the Run SDK
* Schedule, webhook, and durable workflow patterns
* KV store usage for incremental sync and stateful batch processing
* API research and documentation before code generation
* CLI usage for creating projects, managing connections, and deploying
## How it is structured
The skill is a directory of Markdown files. The agent reads the top-level instructions first and only loads the deeper reference material when it is needed, keeping the agent's context focused.
```
coding-versori-sdk/
├── SKILL.md # Core workflow, conventions, and critical rules
└── references/
├── research-docs.md # Research document structure and guidelines
├── sdk-guide.md # Comprehensive Run SDK usage guide
└── cli-usage.md # CLI commands, environment variables, deployment safety
```
The `SKILL.md` file begins with frontmatter containing a `name` and a `description`. The description defines exactly when the skill should activate:
```markdown theme={null}
---
name: coding-versori-sdk
description: Use this skill whenever the user wants to create, debug, or
modify data integration workflows using the versori-run SDK...
---
```
The skill activates on integration-related requests — ETL pipelines, API integrations, webhooks, data synchronisation — and also in any workspace that imports `@versori/run`, even when your prompt contains no Versori keywords.
## Platform behaviour it encodes
Because the skill is applied at the point of use, it encodes platform behaviour that an AI model could not infer on its own. For example, it instructs the agent to:
* Inspect a project's systems with `versori projects systems list` before generating any `fetch()` paths
* Account for platform-specific behaviour, such as the runtime stripping a trailing `/api` segment from a system's base URL
* Resolve the `connection` parameter against a project's **system** name, so the underlying credentials can be swapped without editing workflow code
* Prefer activation variables and the KV store for configuration and state, rather than hard-coded values
* Read the official documentation and inspect your project's actual systems and connections rather than relying on assumptions, so generated code matches your real configuration
## Reference projects
When generating code, the skill consults your organisation's **starred reference projects** — the blessed examples for your org. Before writing a new workflow, the agent reads these projects and follows their structure, naming conventions, and error-handling patterns. This means the skill adapts to how your organisation actually builds integrations, not just to generic defaults.
See [Reference projects](/latest/cli/commands/projects) for how to star a project.
## Related docs
* [Skills](/latest/ai-tooling/skills) — how skills are loaded and applied in the Versori platform
* [Skills Marketplace](/latest/ai-tooling/marketplace): the catalogue of platform skills for your organisation
* [Workflow](/latest/ai-tooling/workflow) — the step-by-step process the skill drives
* [Run SDK](/latest/run-sdk/latest/introduction) — the SDK the skill generates code with
* [`versori skills` command](/latest/cli/commands/skills) — download and packaging options
# Workflow
Source: https://docs.versori.com/latest/ai-tooling/workflow
The structured 8-step process the Versori skill follows to build integrations.
When activated, the skill guides your AI tool through a structured workflow that mirrors the Versori integration lifecycle. Each step builds on the previous one, ensuring integrations are researched, built, tested, and deployed consistently.
## The 8-step workflow
The skill confirms that your request is related to data integration — ETL pipelines, API integrations, webhooks, data synchronisation, or similar tasks. If the request falls outside this scope, it lets you know and suggests alternatives.
The skill prepares a structured research document covering:
* The source and target systems involved
* API endpoints, authentication methods, and data models
* Field mappings between systems
* Trigger types (webhook, schedule, or manual)
* Implementation considerations such as rate limits, pagination, and error handling
This mirrors what the [Plan agent](/latest/how-it-works/plan) does in the Versori platform UI.
Using the research document, the agent runs CLI commands to bootstrap systems on the Versori platform:
```sh theme={null}
versori systems create --name "Shopify" --base-url "https://my-store.myshopify.com"
```
It creates each system identified in the research phase and links them to your project.
The agent creates authenticated connections for each system using the appropriate authentication method (API key, OAuth 2.0, etc.):
```sh theme={null}
versori connections create --system --auth-type api-key
```
See the [Connections guide](/latest/cli/connections) for details on authentication methods and connection configuration.
The agent generates TypeScript workflows using the [Versori Run SDK](/latest/run-sdk/latest/introduction). It writes workflow files that:
* Define triggers (webhook or schedule)
* Map data between source and target systems
* Handle authentication via connections
* Include error handling and logging
```typescript theme={null}
import { webhook, fn, http } from '@versori/run';
export const syncOrders = webhook('sync-orders')
.then(
fn('transform', (ctx) => {
return { /* mapped data */ };
})
)
.then(
http('create-record', { connection: 'target-system' }, async ({ fetch, data }) => {
const response = await fetch('/api/records', {
method: 'POST',
body: JSON.stringify(data),
});
return response.json();
})
);
```
The agent writes Deno test files for pure functions — data transformations, field mappings, and validation logic. This ensures your business logic is correct before deployment.
The agent runs local verification to catch issues before deployment:
```sh theme={null}
deno check src/workflows.ts
deno test
```
Type errors and test failures are resolved before proceeding.
Once verification passes, the agent deploys the integration:
```sh theme={null}
versori projects deploy --environment production
```
See the [Project Workflow guide](/latest/cli/workflow) for details on deployment, versioning, and monitoring.
## What the skill handles vs. what you handle
| The skill | You |
| -------------------------------------------------------- | ---------------------------------------------------- |
| Researches APIs, auth methods, and data models | Provides the integration requirements and context |
| Generates CLI commands to set up systems and connections | Reviews and approves system/connection configuration |
| Writes TypeScript workflow code using the Run SDK | Reviews generated code for correctness |
| Writes and runs tests for business logic | Provides test cases or edge cases to cover |
| Runs type checking and tests locally | Supplies API credentials and access tokens |
| Deploys via the CLI | Confirms the target environment |
## Example interaction
**Your prompt:**
```
Build an integration that syncs new Shopify orders to QuickBooks Online as sales receipts.
Use OAuth 2.0 Authorization Code for QuickBooks and API key for Shopify.
Run on webhook — trigger whenever a new order is created in Shopify.
```
**What the skill does:**
1. Produces a research document covering both Shopify and QuickBooks APIs
2. Creates systems for Shopify and QuickBooks on the platform
3. Sets up connections with the specified authentication methods
4. Generates a webhook workflow that receives Shopify order events, transforms the data, and creates sales receipts in QuickBooks
5. Writes tests for the data transformation logic
6. Runs verification and deploys
## Related docs
* [Plan agent](/latest/how-it-works/plan) — how Versori researches integrations
* [Connections guide](/latest/cli/connections) — managing authenticated connections
* [Run SDK](/latest/run-sdk/latest/introduction) — the SDK used to build workflows
* [Project Workflow](/latest/cli/workflow) — CLI-based project lifecycle
# Authentication
Source: https://docs.versori.com/latest/api-reference/authentication
Learn how to authenticate with the Versori Platform.
This section provides an overview of how to authenticate with Versori APIs.
# Signing Keys
The first step is that you should generate a signing key for your organisation. These can be generated in the Signing keys section of the account settings page. To get there you can click on the My Account button and then on View Account. On key creation, you will be able to copy or download your private key as a `.pem` file.
**Note that once you leave this page, you will be unable to view your private key.** You should keep private keys secret, obviously!
The keys are in PKCS #8 format. It is with this private key that your backend should use to sign JWTs for your end users when making requests to Versori APIs.
If you require a long lived JWT to access the Versori platform, for example via curl or Postman, you can generate one by clicking on the "Sign JWT" button. To see how to use this JWT to authenticate API calls, see the [Authenticating API calls](#authenticating-api-calls) section below. This JWT is not suitable for creating or managing end users.
## Signing JWTs on behalf of your users with your signing keys
This section outlines how to programmatically sign JWTs on behalf of your end users using your signing key. This is relevant if your integrations are intended to act on behalf of your users.
When making calls to Versori APIs to create a user, activating users, manage connections etc, you need to sign a JWT with your organisations private key and make the subject your end users external ID. A couple examples of signing a JWT are shown below:
```typescript TypeScript theme={null}
import { importPKCS8, SignJWT } from 'jose';
async function signJWT(privateKey: string, signingkeyId: string, externalId: string): Promise {
const key = await importPKCS8(privateKey, 'RS256');
const ISSUER = `https://versori.com/sk/${signingkeyId}`;
const token = await new SignJWT({ sub: externalId })
.setIssuer(ISSUER)
.setIssuedAt()
.setExpirationTime('1 hour')
.setProtectedHeader({ alg: 'RS256' })
.sign(key);
return token;
}
```
```go Go theme={null}
import (
"time"
"github.com/golang-jwt/jwt/v5"
)
func SignJWT(privateKey []byte, signingKeyId string, externalId string) (string, error) {
key, err := jwt.ParseRSAPrivateKeyFromPEM(privateKey)
if err != nil {
return "", err
}
claims := jwt.MapClaims{
"sub": externalId,
"iss": "https://versori.com/sk/" + signingKeyId,
"iat": time.Now().Unix(),
"exp": time.Now().Add(time.Hour).Unix(),
}
token := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
signedToken, err := token.SignedString(key)
if err != nil {
return "", err
}
return signedToken, nil
}
```
```python Python theme={null}
# Using PyJWT library: https://pyjwt.readthedocs.io/en/stable/index.html
import jwt
import time
def sign_jwt(private_key: str, signing_key_id: str, external_id: str) -> str:
current_time = int(time.time())
payload = {
"sub": external_id,
"iss": f"https://versori.com/sk/{signing_key_id}",
"iat": current_time,
"exp": current_time + 3600, # 1 hour expiration
}
token = jwt.encode(payload, private_key, algorithm="RS256")
return token
```
You can find your `signingKeyId` on the signing key page, shown above, to set the issuer claim.
## Authenticating API calls
You can authenticate calls to Versori APIs by setting the `Authorization` header to a value of `JWT {jwt-goes-here}`, for example:
```bash theme={null}
curl -X GET https://platform.versori.com/api/v2/o//users/
-H "Authorization: JWT {jwt-goes-here}"
```
# Getting Started
Source: https://docs.versori.com/latest/api-reference/getting-started
Get started with Versori APIs.
TBA
# Getting Started
Source: https://docs.versori.com/latest/api-reference/platform-api/getting-started
Get started with the Versori Platform API.
TBA
# Changelog
Source: https://docs.versori.com/latest/changelog
Product updates and announcements
## Features
* **Skills marketplace.** Browse a catalogue of ready-made skills and add them to your organisation, instead of
writing every skill yourself. Fork any marketplace skill to get an editable copy of your own. The AI can also
suggest a relevant skill while you work, and nothing is added unless you approve it. See the
[Skills Marketplace](/latest/ai-tooling/marketplace).
* **Skills have moved to their own page.** Your organisation's skills are now under **Skills** in the left-hand
navigation, rather than in organisation settings, with search, category and status filtering, and sorting.
See [Manage Your Skills](/latest/ai-tooling/manage-skills).
## Improvements
* Skills now apply across your whole organisation, so there is no longer a per-integration step to attach them.
Adding a skill is what makes it available. Mark one as **Mandatory** to apply it to every request, or leave it
**Optional** to be loaded when its description matches the work in hand. See
[How the AI applies skills](/latest/ai-tooling/skills#how-the-ai-applies-skills).
## Improvements
* The message box in chat now grows with your message and supports much longer text before you need to scroll, making it easier to write and review longer prompts.
## Bug fixes
* Fixed an issue in the Connect tab where systems with multiple connection templates could not be selected or identified independently of one another.
## Features
* The Build agent can now deploy your project for you. When it proposes a deployment, you'll see a confirmation card in the chat — approve it to deploy right away, or decline and keep working. Clear messages are shown if a deploy can't go ahead.
## Features
* Plan and Build are now one conversation. Use the Plan/Build toggle next to the message box to research and scope your integration with the planning agent, then switch to Build to implement it — all in a single chat with shared context.
## Improvements
* Added support for OAuth2 connections where the token refresh endpoint differs from the token endpoint.
## Improvements
* The Issues tab has been reworked to improve readability by adding search, improving the existing filtering and sort features, and enabling pagination.
## Features
* Multiple chat support in Build
## Improvements
* The Connect tab has been redesigned to be more user-friendly and intuitive. The new design removes the sidebar once used for connecting and managing connectors, and instead displays the connector details in the main content area. Creating new connections, configuring an embedded connector, or selecting an existing connection is now quicker and more seamless. You will still find the connector endpoints, discovered during planning, available to test.
* The Opus 4.6 model has been added into the Plan Tab
## Bug fixes
* Gracefully handle JSON.parse errors on AI returned data
## Improvements
* Gemini 3 Flash support in the Build tab
* Search in new tab menu
## Bug fixes
* Fixed file tracking of either version or latest draft files against deployed files. File diff changes are visible in the Changes to Deploy button located in the header.
* For members of multiple organisations - active organisation is now determined by the org query param, context switching between tabs is now actively efficient.
* On error of deployment, the retry deployment button now correctly tracks whether a version or the latest draft was deployed and triggers the re-deployment of the correct files.
## Features
* Versions has been rolled out into the UI. Versions can be created at any time and are created on deployment of the current working draft project. If a previous version is selected and the user then saves a new file change on top of this version, the user will no longer be on that version but rather the 'Current Draft' and a new version can be created from this point.
* Accept and undo AI modified file changes. After AI has applied a change, you can now either accept or undo any file changes allowing for greater control.
## Improvements
* We have added the option to save individual files in the UI giving you greater control. This is especially important when AI is editing multiple files in one action or you are manually editing multiple files at once and want more granular control. The Save All function is still available although the button has moved inside the Build tab as it is more contextually relevant here.
## Bug fixes
* Correct handling of AI file deletion.
## Improvements
* The plan chat now offers the option to switch between AI models - Gemini 3 Pro and Claude Sonnet 4.5
## Improvements
* The Console has been removed and it‘s features moved. You will now find deployment logs, execution trace history, embedded users, and the runtime test features in their respective tabs, alongside all existing tabs.
* For your Embedded users, now located in an integration tab - including a re-design and updated UX, you can now manage activated users, including updating their activation variables and viewing active connections.
* The Flow preview will now auto generate for you after initial code generation.
## Improvements
* You can now access nested folders and files for your assets in the asset picker
## Bug fixes
* Connector authentication information correctly updates when switching between connectors.
## Improvements
* We have released an updated version of the Plan tab, including more fine grained searching of information, auto generation of workflows and identification of connectors feedback.
## Bug fixes
* Connector authentication information correctly updates when switching between connectors.
## Improvements
* You can search logs inside the test console
## Features
* Added new workflow testing mode to the Build tab, allowing integrations to be tested before deployment.
* Add support to upload JSON (.json), plain text (.txt), and markdown (.md) file attachments in chat.
## Features
Project build process revamped to the "Plan", "Connect", "Build", "Deploy" flow, including
touch-ups to the UIs and an improved UX for connecting to and testing Connectors.
## Bug fixes
The AI should be more aware of SDK features which are available in your Projects, and stop
hallucinating about features that aren't available.
## Breaking changes
There are no breaking changes to the APIs or SDKs, but you may realise some functionality has
moved around in the UI.
## Deprecations
There are no deprecations in this release.
## Documentation updates
This release fully revamps our documentation site, as well as moving all documentation of our
legacy platform under the "Legacy" version, which can be accessed by the top-left dropdown menu.
# completion
Source: https://docs.versori.com/latest/cli/commands/completion
Generate the autocompletion script for the specified shell
Generate the autocompletion script for versori for the specified shell.
See each sub-command's help for details on how to use the generated script.
## Subcommands
| Subcommand | Description |
| ------------ | ------------------------------------------------- |
| `bash` | Generate the autocompletion script for bash |
| `fish` | Generate the autocompletion script for fish |
| `powershell` | Generate the autocompletion script for powershell |
| `zsh` | Generate the autocompletion script for zsh |
***
### `versori completion bash`
Generate the autocompletion script for the bash shell.
This script depends on the 'bash-completion' package.
If it is not installed already, you can install it via your OS's package manager.
To load completions in your current shell session:
```sh theme={null}
source <(versori completion bash)
```
To load completions for every new session, execute once:
#### Linux
```sh theme={null}
versori completion bash > /etc/bash_completion.d/versori
```
#### macOS
```sh theme={null}
versori completion bash > $(brew --prefix)/etc/bash_completion.d/versori
```
You will need to start a new shell for this setup to take effect.
```sh theme={null}
versori completion bash
```
**Flags:**
* `-h`, `--help`: help for bash
* `--no-descriptions`: disable completion descriptions
***
### `versori completion fish`
Generate the autocompletion script for the fish shell.
To load completions in your current shell session:
```sh theme={null}
versori completion fish | source
```
To load completions for every new session, execute once:
```sh theme={null}
versori completion fish > ~/.config/fish/completions/versori.fish
```
You will need to start a new shell for this setup to take effect.
```sh theme={null}
versori completion fish [flags]
```
**Flags:**
* `-h`, `--help`: help for fish
* `--no-descriptions`: disable completion descriptions
***
### `versori completion powershell`
Generate the autocompletion script for powershell.
To load completions in your current shell session:
```sh theme={null}
versori completion powershell | Out-String | Invoke-Expression
```
To load completions for every new session, add the output of the above command
to your powershell profile.
```sh theme={null}
versori completion powershell [flags]
```
**Flags:**
* `-h`, `--help`: help for powershell
* `--no-descriptions`: disable completion descriptions
***
### `versori completion zsh`
Generate the autocompletion script for the zsh shell.
If shell completion is not already enabled in your environment you will need
to enable it. You can execute the following once:
```sh theme={null}
echo "autoload -U compinit; compinit" >> ~/.zshrc
```
To load completions in your current shell session:
```sh theme={null}
source <(versori completion zsh)
```
To load completions for every new session, execute once:
#### Linux
```sh theme={null}
versori completion zsh > "${fpath[1]}/_versori"
```
#### macOS
```sh theme={null}
versori completion zsh > $(brew --prefix)/share/zsh/site-functions/_versori
```
You will need to start a new shell for this setup to take effect.
```sh theme={null}
versori completion zsh [flags]
```
**Flags:**
* `-h`, `--help`: help for zsh
* `--no-descriptions`: disable completion descriptions
***
# connections
Source: https://docs.versori.com/latest/cli/commands/connections
Manage connections
## Subcommands
| Subcommand | Description |
| ---------- | ------------------------------------------------------ |
| `create` | Create a new connection to a connection template |
| `delete` | Delete a connection |
| `list` | Lists connections for the current organisation context |
| `unlink` | Unlink a connection from an environment template |
***
### `versori connections create`
Create a new connection to a connection template. If an end user's external ID is provided,
The connection will be created as a dynamic connection for that end user, otherwise it will be created as a static connection.
If a base URL is not provided, it will default to the system's base URL defined in the connection template.
```sh theme={null}
versori connections create --project --environment --name --template-id [--external-id ] [--base-url ] [--]... [flags]
```
**Flags:**
* `--api-key`: API key for authentication
* `--base-url`: Base URL for the connection, if not provided it will default to the systems base URL
* `--bypass`: Whether to bypass authentication (if supported by the connection template)
* `--client-id`: OAuth2 client id for use with an oauth2 client connection
* `--client-secret`: OAuth2 client secret for use with an oauth2 client connection
* `--env-file`: Path to .env file for resolving \$VARIABLE references in credential flags
* `--environment`: The environment name within the project
* `--external-id`: External ID of the end user for the connection, if not provided the connection will be created as a static connection
* `-h`, `--help`: help for create
* `--name`: Name of the connection
* `--password`: Password for HTTP Basic authentication or OAuth2 password grant type
* `--project`: Project ID; defaults from .versori when inside a synced project directory.
* `--template-id`: ID of the connection template to connect to
* `--token-url`: OAuth2 token URL for use with an oauth2 client connection. Defaults to the token URL defined in the connection template.
* `--username`: Username for HTTP Basic authentication or OAuth2 password grant type
***
### `versori connections delete`
Delete a connection (DELETE /o/\{organisation}/connections/\{id}).
This removes the connection itself. Unlink it from an environment first if you
only want to clear the active connection. Pass --yes or --confirm in non-interactive shells;
the VS Code extension always passes --yes after its own confirmation modal.
```sh theme={null}
versori connections delete --id [--yes] [flags]
```
**Flags:**
* `--confirm`: Skip the confirmation prompt (same as --yes)
* `-h`, `--help`: help for delete
* `--id`: ULID of the connection to delete
* `-y`, `--yes`: Skip the confirmation prompt
***
### `versori connections list`
```sh theme={null}
versori connections list [flags]
```
**Flags:**
* `--end-user`: Filter by end-user ULID or external ID (external IDs are resolved client-side)
* `-h`, `--help`: help for list
* `--system`: Filter by system ID
***
### `versori connections unlink`
Unlink a connection from an environment (DELETE /o/\{organisation}/connections/\{id}/link).
The connection itself is kept. Pass --yes or --confirm in non-interactive shells; the VS Code
extension always passes --yes after its own confirmation modal.
```sh theme={null}
versori connections unlink --id --template-id [--yes] [flags]
```
**Flags:**
* `--confirm`: Skip the confirmation prompt (same as --yes)
* `-h`, `--help`: help for unlink
* `--id`: ULID of the connection to unlink
* `--template-id`: Connection template ID (environment system) to unlink from
* `-y`, `--yes`: Skip the confirmation prompt
***
# context
Source: https://docs.versori.com/latest/cli/commands/context
Manages the authentications to the Versori platform
Context sets the configuration for your CLI session.
It allows you to manage your authentication tokens and organisations.
## Subcommands
| Subcommand | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `add` | Add a new context to your config and selects it as the default. It requires you generate a JWT token from the Versori console. You can generate the JWT here [https://ai.versori.com/account?content=keys](https://ai.versori.com/account?content=keys) |
| `list` | List currently configured contexts. \* denotes the active context. |
| `rm` | Remove a configured context. |
| `select` | Changes the active context. |
| `show` | Show the active context (without secrets). |
***
### `versori context add`
```sh theme={null}
versori context add --name --organisation --jwt [flags]
```
**Flags:**
* `-h`, `--help`: help for add
* `--jwt`: JWT token to use with the context. If the value is -, it will be read from stdin.
* `--name`: Name of the context
* `--organisation`: Organisation ID to use with the context
***
### `versori context list`
```sh theme={null}
versori context list [flags]
```
**Flags:**
* `-h`, `--help`: help for list
***
### `versori context rm`
```sh theme={null}
versori context rm [flags]
```
**Flags:**
* `-h`, `--help`: help for rm
***
### `versori context select`
```sh theme={null}
versori context select [flags]
```
**Flags:**
* `-h`, `--help`: help for select
***
### `versori context show`
```sh theme={null}
versori context show [flags]
```
**Flags:**
* `-h`, `--help`: help for show
***
# execution-pools
Source: https://docs.versori.com/latest/cli/commands/execution-pools
Manage execution pools
## Subcommands
| Subcommand | Description |
| ---------- | ------------------------------------------------------------ |
| `list` | Lists available execution pools for the current organisation |
***
### `versori execution-pools list`
```sh theme={null}
versori execution-pools list [flags]
```
**Flags:**
* `-h`, `--help`: help for list
***
# issues
Source: https://docs.versori.com/latest/cli/commands/issues
List, inspect, and update issues
Inspect and manage issues raised in the organisation.
Read commands (list, get) are safe to run for diagnosis. The update command changes live issue
state (e.g. acknowledging or resolving) and should only be run when explicitly requested.
## Subcommands
| Subcommand | Description |
| ---------- | ---------------------------------------- |
| `get` | Get full detail for a single issue |
| `list` | List issues for the current organisation |
| `update` | Update an issue's status or severity |
***
### `versori issues get`
```sh theme={null}
versori issues get [flags]
```
**Flags:**
* `-h`, `--help`: help for get
* `--project`: Project ID; defaults from .versori when inside a synced project directory.
***
### `versori issues list`
List issues raised across the organisation (via ctx.createIssue(), unhandled workflow errors, or
platform events such as an out-of-memory kill).
Filters (all optional) narrow server-side by status, project, environment, and severity. Inside a
synced project directory the project filter defaults from .versori. An OOM-killed project surfaces
here as an issue titled "OOM Killed" — inspect it with 'issues get \'.
```sh theme={null}
versori issues list [flags]
```
**Flags:**
* `--after`: Pagination cursor: pass a prior response's last issue ID to fetch the next page
* `--before`: Pagination cursor for the previous page
* `--environment`: Filter by environment ID
* `--first`: Max issues to return (0 lets the server default apply)
* `-h`, `--help`: help for list
* `--project`: Project ID; defaults from .versori when inside a synced project directory.
* `--severity`: Filter by severity (critical, high, low, medium)
* `--status`: Filter by status (open, closed, acked, resolved)
***
### `versori issues update`
Update the editable fields of an issue. Common uses:
update \ --status acked # acknowledge
update \ --status resolved # mark resolved (server records resolved\_at)
Mirrors the platform: only the fields you pass are sent. This is a mutation — run it only when
explicitly asked.
```sh theme={null}
versori issues update [flags]
```
**Flags:**
* `-h`, `--help`: help for update
* `--severity`: New severity (critical, high, low, medium)
* `--status`: New status (open, closed, acked, resolved)
***
# kv
Source: https://docs.versori.com/latest/cli/commands/kv
Inspect and manage KV store entries
Inspect and manage entries in a project's KV store.
Read commands (stores list, list, count, get) are safe to run for diagnosis. Mutation commands
(set, delete, wipe) change live workflow state and should only be run when explicitly requested.
## Subcommands
| Subcommand | Description |
| ---------- | ---------------------------------------------------- |
| `count` | Count KV entries matching a prefix |
| `delete` | Delete a single KV entry (mutation) |
| `get` | Get a single KV entry by key |
| `list` | List KV entries under a prefix |
| `set` | Set a KV entry (mutation) |
| `stores` | Inspect KV stores |
| `wipe` | Delete every KV entry under a prefix (bulk mutation) |
***
### `versori kv count`
Count the entries matching a key prefix. Unlike list, this returns a total rather than a
capped page, so it is the right way to answer "how many items are under this prefix?".
Targeting works the same as kv list: --store \ (raw) or --scope \ (friendly), with
optional --prefix segments to narrow further.
```sh theme={null}
versori kv count (--store | --scope ...) [--prefix ]... [flags]
```
**Flags:**
* `--activation-id`: Activation ID (optional; narrows project/execution scope).
* `--environment`: Environment name, e.g. production (friendly mode).
* `--execution-id`: Execution ID (required for --scope execution).
* `--external-id`: End-user external ID (required for --scope user).
* `--full-keys`: Show full resolved keys instead of stripping the scope prefix.
* `-h`, `--help`: help for count
* `--prefix`: Key prefix segment (repeatable).
* `--project`: Project ID; defaults from .versori when inside a synced project directory.
* `--scope`: Friendly scope: organization | workspace | project | user | execution.
* `--store`: KV store ID (raw mode). Mutually exclusive with --scope.
***
### `versori kv delete`
Delete one entry by key.
WARNING: this mutates live workflow state. Only run it when explicitly asked to delete a specific
key — never as a side-effect of debugging. This removes a single key only; to delete everything
under a prefix use kv wipe.
Confirms before deleting unless --yes or --confirm is passed; in non-interactive shells one of those flags is required.
```sh theme={null}
versori kv delete (--store | --scope ...) --key [flags]
```
**Flags:**
* `--activation-id`: Activation ID (optional; narrows project/execution scope).
* `--confirm`: Skip the confirmation prompt (same as --yes)
* `--environment`: Environment name, e.g. production (friendly mode).
* `--execution-id`: Execution ID (required for --scope execution).
* `--external-id`: End-user external ID (required for --scope user).
* `--full-keys`: Show full resolved keys instead of stripping the scope prefix.
* `-h`, `--help`: help for delete
* `--key`: Key to delete (slash-delimited).
* `--project`: Project ID; defaults from .versori when inside a synced project directory.
* `--scope`: Friendly scope: organization | workspace | project | user | execution.
* `--store`: KV store ID (raw mode). Mutually exclusive with --scope.
* `-y`, `--yes`: Skip the confirmation prompt
***
### `versori kv get`
Fetch one entry by its key. In raw mode (--store) the --key is the literal full key. In
friendly mode (--scope) the --key is relative to the scope and the CLI prepends the scope prefix.
Values written by workflows are JSON-encoded strings and are unwrapped one level by default; pass
\--raw-values to show exactly what is stored.
```sh theme={null}
versori kv get (--store | --scope ...) --key [flags]
```
**Flags:**
* `--activation-id`: Activation ID (optional; narrows project/execution scope).
* `--environment`: Environment name, e.g. production (friendly mode).
* `--execution-id`: Execution ID (required for --scope execution).
* `--external-id`: End-user external ID (required for --scope user).
* `--full-keys`: Show full resolved keys instead of stripping the scope prefix.
* `-h`, `--help`: help for get
* `--key`: Key to fetch (slash-delimited, e.g. cursor/orders).
* `--project`: Project ID; defaults from .versori when inside a synced project directory.
* `--raw-values`: Show the value exactly as stored (no JSON-string unwrapping).
* `--scope`: Friendly scope: organization | workspace | project | user | execution.
* `--store`: KV store ID (raw mode). Mutually exclusive with --scope.
***
### `versori kv list`
List key/value entries in a store, optionally narrowed by a key prefix.
Targeting (pick one):
\--store \ raw mode; --prefix segments are the literal key prefix.
\--scope \ friendly mode; the CLI derives the store + scope prefix and strips it from
displayed keys (use --full-keys to keep it). Extra --prefix segments narrow
within the scope.
Values written by workflows are JSON-encoded strings; by default they are unwrapped one level for
readability. Pass --raw-values to show exactly what is stored. For nested values prefer -o json or
-o yaml, which preserve the full structure (table truncates the value column).
Beyond the prefix, entries can be filtered server-side by creation time (--created-after /
\--created-before) and by metadata (--metadata key=value).
Pagination is cursor-based, ordered newest-first by the entry's internal ID (not by key). A page
is capped (max 100). To page through results, pass the previous response's opaque nextCursor to
\--after — never a key. An empty nextCursor means you have reached the end; it does not mean more
pages are hidden. Use 'kv count' for an authoritative total under a prefix.
```sh theme={null}
versori kv list (--store | --scope ...) [--prefix ]... [flags]
```
**Flags:**
* `--activation-id`: Activation ID (optional; narrows project/execution scope).
* `--after`: Pagination cursor for the next page: pass the previous response's opaque nextCursor verbatim (NOT a key). Empty nextCursor means there are no more entries.
* `--before`: Pagination cursor for the previous page: pass an opaque prevCursor from a prior response (NOT a key).
* `--created-after`: Only entries created at/after this time (RFC3339 or YYYY-MM-DD).
* `--created-before`: Only entries created at/before this time (RFC3339 or YYYY-MM-DD).
* `--environment`: Environment name, e.g. production (friendly mode).
* `--execution-id`: Execution ID (required for --scope execution).
* `--external-id`: End-user external ID (required for --scope user).
* `--full-keys`: Show full resolved keys instead of stripping the scope prefix.
* `-h`, `--help`: help for list
* `--limit`: Max entries to return (1-100; 0 lets the server default apply).
* `--metadata`: Filter by metadata key=value (repeatable; value parsed as JSON when valid, else a string).
* `--prefix`: Key prefix segment (repeatable).
* `--project`: Project ID; defaults from .versori when inside a synced project directory.
* `--raw-values`: Show values exactly as stored (no JSON-string unwrapping).
* `--reverse`: Reverse the sort order.
* `--scope`: Friendly scope: organization | workspace | project | user | execution.
* `--store`: KV store ID (raw mode). Mutually exclusive with --scope.
***
### `versori kv set`
Write a value at a key.
WARNING: this mutates live workflow state (cursors, dedupe keys, batch progress). Only run it when
explicitly asked to set a specific key — never as a side-effect of debugging.
The value is JSON-encoded the same way the runtime SDK writes values, so workflow code that reads
the key with ctx.openKv().get() round-trips correctly. A --value that parses as JSON keeps its type
(object/array/number/bool); otherwise it is stored as a string.
Confirms before writing unless --yes or --confirm is passed; in non-interactive shells one of those flags is required.
```sh theme={null}
versori kv set (--store | --scope ...) --key (--value | --value-file ) [flags]
```
**Flags:**
* `--activation-id`: Activation ID (optional; narrows project/execution scope).
* `--confirm`: Skip the confirmation prompt (same as --yes)
* `--environment`: Environment name, e.g. production (friendly mode).
* `--execution-id`: Execution ID (required for --scope execution).
* `--expire-in`: TTL in milliseconds (0 = no expiry).
* `--external-id`: End-user external ID (required for --scope user).
* `--full-keys`: Show full resolved keys instead of stripping the scope prefix.
* `-h`, `--help`: help for set
* `--if-not-exists`: Only set if the key does not already exist.
* `--key`: Key to set (slash-delimited).
* `--project`: Project ID; defaults from .versori when inside a synced project directory.
* `--scope`: Friendly scope: organization | workspace | project | user | execution.
* `--store`: KV store ID (raw mode). Mutually exclusive with --scope.
* `--value`: Value to store (JSON when valid, otherwise a string).
* `--value-file`: Read the value from a file instead of --value.
* `-y`, `--yes`: Skip the confirmation prompt
***
### `versori kv stores`
See the [stores reference](kv/stores) for detailed subcommands to inspect kv stores.
***
### `versori kv wipe`
Cascade-delete all entries under a key prefix.
WARNING: this is the most destructive KV operation and mutates live workflow state in bulk. Only
run it when explicitly asked to wipe a specific prefix or scope — never as a side-effect of
debugging or to "clean up".
An empty prefix is refused (that would target the entire store). The command always counts the
matching entries first and prints what would be deleted; it only proceeds when --confirm is passed,
so running it without --confirm is a safe dry-run.
```sh theme={null}
versori kv wipe (--store --prefix ... | --scope ...) --confirm [flags]
```
**Flags:**
* `--activation-id`: Activation ID (optional; narrows project/execution scope).
* `--confirm`: Actually perform the deletion (without it, prints a dry-run preview).
* `--environment`: Environment name, e.g. production (friendly mode).
* `--execution-id`: Execution ID (required for --scope execution).
* `--external-id`: End-user external ID (required for --scope user).
* `--full-keys`: Show full resolved keys instead of stripping the scope prefix.
* `-h`, `--help`: help for wipe
* `--prefix`: Key prefix segment (repeatable). Required in raw mode.
* `--project`: Project ID; defaults from .versori when inside a synced project directory.
* `--scope`: Friendly scope: organization | workspace | project | user | execution.
* `--store`: KV store ID (raw mode). Mutually exclusive with --scope.
***
# kv stores
Source: https://docs.versori.com/latest/cli/commands/kv/stores
Inspect KV stores
## Subcommands
| Subcommand | Description |
| ---------- | ------------------------------------------ |
| `list` | List KV stores in the current organisation |
***
### `versori kv stores list`
List the KV stores in the current organisation context. Stores are created lazily by the
runtime on first write and named ORG\_\, PROJECT\_\, or EXECUTION\_\. Use the
returned store ID with the other kv commands' --store flag, or address a store by --scope.
```sh theme={null}
versori kv stores list [flags]
```
**Flags:**
* `-h`, `--help`: help for list
***
# notifications
Source: https://docs.versori.com/latest/cli/commands/notifications
Manage notification channels and project notification bindings
## Subcommands
| Subcommand | Description |
| ---------- | ----------------------------------------------------------------------- |
| `channels` | Manage organisation-wide notification channels |
| `project` | Link, unlink, and list notification channels on a project + environment |
***
### `versori notifications channels`
See the [channels reference](notifications/channels) for detailed subcommands to manage organisation-wide notification channels.
***
### `versori notifications project`
See the [project reference](notifications/project) for detailed subcommands to link, unlink, and list notification channels on a project + environment
.
***
# notifications channels
Source: https://docs.versori.com/latest/cli/commands/notifications/channels
Manage organisation-wide notification channels
## Subcommands
| Subcommand | Description |
| ---------- | ----------------------------------------------------------------- |
| `create` | Create an email notification channel for the current organisation |
| `delete` | Delete an organisation-wide notification channel |
| `list` | List notification channels in the current organisation |
***
### `versori notifications channels create`
Create an email notification channel. Channels are organisation-scoped; bind one to a project
with 'versori notifications project link'.
Pass --email to set the primary recipient. Use --cc (repeatable) for additional recipients. The
CLI does not derive an email from the active context's token — service-key tokens carry no user
identity, so the recipient must be supplied explicitly.
```sh theme={null}
versori notifications channels create --name --email [--cc ]... [flags]
```
**Flags:**
* `--cc`: Additional addresses to CC (repeatable)
* `--email`: Primary email address (required)
* `-h`, `--help`: help for create
* `--name`: Display name for the channel
***
### `versori notifications channels delete`
Delete a notification channel from the current organisation. Any project bindings using this
channel will stop firing (delete the bindings first with 'versori notifications project unlink'
if you want a graceful tear-down).
If --channel-id is omitted, the CLI shows a picker of existing channels. Confirms before deleting
unless --yes or --confirm is passed.
```sh theme={null}
versori notifications channels delete --channel-id [--yes] [flags]
```
**Flags:**
* `--channel-id`: ULID of the channel to delete (prompts a picker if omitted)
* `--confirm`: Skip the confirmation prompt (same as --yes)
* `-h`, `--help`: help for delete
* `-y`, `--yes`: Skip the confirmation prompt
***
### `versori notifications channels list`
```sh theme={null}
versori notifications channels list [flags]
```
**Flags:**
* `-h`, `--help`: help for list
***
# notifications project
Source: https://docs.versori.com/latest/cli/commands/notifications/project
Link, unlink, and list notification channels on a project + environment
## Subcommands
| Subcommand | Description |
| ---------- | -------------------------------------------------------------------------- |
| `link` | Link an existing notification channel to this project + environment |
| `list` | List notifications bound to a project (optionally filtered by environment) |
| `unlink` | Unlink a notification channel from this project + environment |
***
### `versori notifications project link`
Link an existing notification channel (created with 'versori notifications channels create')
to a project + environment. After linking, issues created in that environment by workflow code
('ctx.createIssue()' or '.catch()' blocks) also trigger an email through the channel. Issues
are always visible in the Issues UI without a linked channel — linking only adds email delivery.
If --channel-id or --environment is omitted, the CLI presents an interactive picker of the
available channels/environments by name. --project defaults from .versori when inside a synced
project directory.
```sh theme={null}
versori notifications project link --channel-id --environment [--name