Vertesia Documentation

Vertesia CLI

The Vertesia CLI provides a set of commands to manage and interact with the Vertesia Platform. This documentation covers all available commands, grouped by their logical functionality, and provides examples on how to use each command.

Installation

To install the CLI, follow these steps:

  1. Ensure Node.js is installed: The Vertesia CLI requires Node.js. You can download and install it from nodejs.org. You can verify Node.js is installed by running:

    node --version

  2. Install the Vertesia CLI globally: Open your terminal and run the following command to install the Vertesia CLI globally using npm:

    npm install -g @vertesia/cli

  3. Verify the installation: After installation, you can verify that the Vertesia CLI is installed correctly by running:

    vertesia --version

This command displays the version of the CLI installed on your system.

Help

To get help with the CLI.

vertesia --help

To get help with any CLI command.

vertesia help [command]

Option to get help with any CLI command.

vertesia <command> --help

Authentication

Commands to manage authentication.

Commands

  • auth token: Get a JWT token for the API key used in the authentication.

    vertesia auth token

  • auth refresh: Refresh the JWT token.

    vertesia auth pk <projectId> --name <keyName> --ttl <timeToLive>

Profiles

Commands to manage configuration profiles which enable using the CLI with different Vertesia accounts, projects, and infrastructure.

Commands

  • profiles show [name]: Show the configured profiles or the profile with the given name.

    vertesia profiles show [name]

  • profiles use [name]: Switch to another configuration profile.

    vertesia profiles use [name]

  • profiles add [name] [options]: Create a new configuration profile.

    vertesia profiles add [name] --target <environment>

  • profiles edit [name]: Edit an existing configuration profile.

    vertesia profiles edit [name]

  • profiles refresh: Refresh token for the current configuration profile.

    vertesia profiles refresh

  • profiles delete <name>: Delete an existing configuration profile.

    vertesia profiles delete <name>

  • profiles file: Print the configuration file path.

    vertesia profiles file

Projects

Command to list projects.

Command

  • projects: List the projects you have access to.

    vertesia projects

Environments

Command to list environments.

Command

  • envs [envId]: List the environments you have access to.

    vertesia envs [envId]

Interactions

Commands to list interactions, generate test data, run, and search interactions.

Commands

  • interactions: List the interactions available in the current project.

    vertesia interactions

  • interactions <interactionId>: List the details of an interaction given its ID.

    vertesia interactions <interactionId>

  • datagen <interaction> [options]: Generate test data for an interaction given its ID.

    vertesia datagen <interactionId> --env <envId> --model <model> --temperature <value> --output <file> --count <number>

  • run <interactionId> [options]: Run an interaction by ID.

    vertesia run <interactionId> --input <file> --output <file> --data <json> --tags <tags> --temperature <temperature> --model <model> --env <environmentId> --no-stream --count <count> --verbose --jsonl --data-only

  • runs <interactionId> [options]: Search the run history by interaction ID.

    vertesia runs <interactionId> --tags <tags> --status <status> --env <environmentId> --model <model> --query <query> --limit <limit> --page <page> --format <format> --output <file> --before <date> --after <date>

Content Objects

Commands to manage content objects.

Commands

  • content post <file...> [options]: Post a new object to the store. The path to the file can include wildcards by using *.

    vertesia content post <file...> --name <name> --type <type> --mime <mime> --path <parentPath> --recursive

  • content delete <objectId>: Delete an existing object given its ID.

    vertesia content delete <objectId>

  • content get <objectId>: Get an existing object given its ID.

    vertesia content get <objectId>

  • content list <folderPath> [options]: List the objects inside a folder.

    vertesia content list <folderPath> --limit <limit> --skip <skip>

Events

Commands to manage event subscriptions.

Event subscription payloads currently use scope: "project". Account-scoped subscriptions are reserved for a future account-wide automation model.

Commands

  • events subscriptions list: List event subscriptions visible to the current project.

    vertesia events subscriptions list

  • events subscriptions get <subscriptionId> [options]: Get an event subscription by ID.

    vertesia events subscriptions get <subscriptionId> --file <file>

  • events subscriptions create [options]: Create an event subscription from a JSON file.

    vertesia events subscriptions create --file <file>

  • events subscriptions apply [subscriptionId] [options]: Create or update an event subscription from a JSON file.

    vertesia events subscriptions apply <subscriptionId> --file <file>

  • events subscriptions update <subscriptionId> [options]: Update an event subscription from a JSON file.

    vertesia events subscriptions update <subscriptionId> --file <file>

  • events subscriptions delete <subscriptionId>: Delete an event subscription by ID.

    vertesia events subscriptions delete <subscriptionId>

Workflow

Commands to manage workflow definitions.

Commands

  • workflows definitions transpile <files...> [options]: Transpile a TypeScript workflow definition to JSON.

    vertesia workflows definitions transpile <files...> --out <file>

  • workflows definitions create [options]: Create a new workflow definition.

    vertesia workflows definitions create --file <file>

  • workflows definitions apply [workflowId] [options]: Apply a workflow definition.

    vertesia workflows definitions apply [workflowId] --file <file> --skip-validation

  • workflows definitions list: List all workflow definitions.

    vertesia workflows definitions list

  • workflows definitions get <objectId> [options]: Get a workflow definition given its ID.

    vertesia workflows definitions get <objectId> --file <file>

  • workflows definitions delete <objectId>: Delete a workflow definition given its ID.

    vertesia workflows definitions delete <objectId>

Process Tests

Commands to run deterministic process test scenarios against an in-code process (an app: or sys: process) or an inline process definition. Scenarios live in a JSON file next to the process definition in the app repository, so they can be run from CI.

The file mirrors the API payload:

{
  "process": { "id": "app:acme:invoice-review", "app_version": "1.4.2" },
  "scenarios": [
    {
      "id": "happy-path",
      "name": "Happy path",
      "timeout_seconds": 60,
      "initial_context": {},
      "actors": [],
      "fixtures": [],
      "human_actions": [],
      "assertions": { "status": "completed" }
    }
  ]
}

Use "process": { "definition": { ... } } instead of "process": { "id": ... } to test a definition body that is not published yet.

process-tests run waits for the run to finish by default and exits with a CI-friendly status code: 0 when every scenario passed, 1 on a failed or cancelled run (including a scenario timeout), and 2 when the tests could not be started at all — an unreadable file, an invalid payload, or an API error.

Commands

  • process-tests run <file> [options]: Submit the scenarios in the file and wait for the result.

    vertesia process-tests run process-tests.json --app-version 1.4.2 --json

  • process-tests get <run-id> [options]: Show a run and its scenario results, optionally waiting for it to reach a terminal status.

    vertesia process-tests get <run-id> --watch

  • process-tests cancel <run-id>: Cancel a pending or running test run.

    vertesia process-tests cancel <run-id>

Package Management

Commands to manage the Vertesia CLI package.

This command checks if there is a newer version of the CLI available. If a new version is found, it prompts the user to confirm the upgrade. If the user confirms, the Vertesia CLI will update itself to the latest version. If no updates are available, it will notify the user.

Commands

  • upgrade: Upgrade to the latest version of the CLI.

    vertesia upgrade

Was this page helpful?