---
title: "Getting Started"
source: "https://docs.vertesiahq.com/quickstart"
markdown: "https://docs.vertesiahq.com/llms/quickstart.md"
---

# Getting Started

This guide will get you set up and ready to use the Vertesia CLI and SDK.

## Vertesia Studio

In order to create and manage your interaction you need to login to Vertesia Studio (https://cloud.vertesia.io). This is a web application in which you can create and manage your interactions.

Before using the SDK or the CLI to make requests to the platform API, you will need to
create a Project and generate an API Key from your Settings (https://cloud.vertesia.io/settings#keys).

In order to **access and use your interactions** from outside the Studio application, you can use the
Vertesia CLI (https://www.npmjs.com/package/@vertesia/cli). If you want to **integrate your interactions in your own application** you can use the
Vertesia SDK (https://www.npmjs.com/package/@vertesia/client).

Currently, the SDK is only available for JavaScript / TypeScript and code generation is only available for TypeScript. To use Vertesia in other languages you need to directly access the REST API. Please refer to the [API Reference](/api/introduction) guide for information about using the REST API.

There is a second and more efficient way to integrate the interactions in your own application by using *code generation*. **Code generation** will generate high level classes along with TypeScript interfaces to easily access your interactions. We will talk about code generation at the end of this guide.

We will cover the basics of the CLI and of the SDK in the following sections. For full documentation see the projects themselves. Let's start with a quick look at the installation and basic usage of these tools.

## Vertesia CLI

This is a command line application that can be used to access your Vertesia projects.
It was designed to fulfill the following main use cases:

* List and switch between your Vertesia projects
* List the existing interactions and execution environments
* Run interactions once or multiple times over a set of different data inputs
* Generate data inputs to run the interactions against
* Search through the history of runs to inspect detailed results

### Requirements

A TTY terminal and, as for the SDK, Node version 18 or higher is required.

### Installation

```bash
npm -g install @vertesia/cli
```

### Basic Usage

First, a profile must be created. A profile correspond to one organization/project on a vertesia environment (preview or prod). Run the following command:

```bash
vertesia profiles create
```

and follow the interactive prompts.

Once you have entered the profile information, you will be redirected to the authentication page.

Upon successful authentication, the following command:

```bash
vertesia interactions
```

will now list the interactions using the current profile.

Let's run an interaction. We will use the `run` command.

```bash
vertesia run {INTERACTION_ID}
```

This command has plenty of options. It is not the scope of this guide to explain them all.

To summarize we can run an interaction once or multiple times on a set of data inputs (specified from a file using `--input` or inline using `--data`) we can run a interaction by giving some.

When running a single interaction the response will be, by default, streamed on the console.

You can also tag runs to be able to easily search for them later using `vertesia runs`.

**Example:**

```bash
vertesia run --tags testing {INTERACTION_1_ID}
vertesia run --tags testing {INTERACTION_2_ID}
# then, later retrieve the run results having the testing_session tag
vertesia runs --tags testing
```

For more information about the commands use the `help` command or the `-h` flag on a command or check the [CLI documentation](/cli).

## Vertesia SDK

This is a JavaScript SDK that can be used in both Node.js and in the browser.

### Requirements

Node version 18 or higher is required (the fetch API is required).
It will also work with node version 17.5 by using the --experimental-fetch flag

### Installation

```bash
npm install @vertesia/client
```

### Basic Usage

Listing the projects in an organization:

```js
import {VertesiaClient} from "@vertesia/client"

const client = new VertesiaClient({
  site: 'api.vertesia.io',
  apikey: '<YOUR_API_KEY>',
})

const projects = await client.projects.list();

for (const project of projects) {
  console.log(project.name+': '+project.id);
}
```

You can see in the previous example how we initialize the `VertesiaClient` with the API key. The API key will authenticate us on the server and will select the organization to which the key belongs.

Let's list now the interactions in a project

```js
import { VertesiaClient } from "@vertesia/client"

const client = new VertesiaClient({
  site: 'api.vertesia.io',
  apikey: '<YOUR_API_KEY>',
})

const interactions = await client.interactions.list();

for (const interaction of interactions) {
    console.log(interaction.name + ': ' + interaction.id);
}
```

In the example above, you see we added a `projectId` option when instantiating the client. This is the ID of the project we want to access.

Both the API key and the project ID are set when initializing the client and will be used for all the requests made with that client.

You can change the project ID at any time by setting it directly on the client:

```js
client.project = "New Project ID"
```

Both API key and project ID parameters are required when accessing objects in a project. These parameters are sent, as custom headers, along each request to the server and are used to authenticate the user and to select the project.

Let's suppose we created an interaction named "Which Color" which is sending to the LLM an object name to get in response one of its possible colors.

Suppose `interactionId` is the ID of the interaction. We can run it as follows:

```js
import { VertesiaClient } from "@vertesia/client"

const client = new VertesiaClient({
  site: 'api.vertesia.io',
  apikey: '<YOUR_API_KEY>',
})

// Note that the interactionId argument must be a valid interaction ID which belongs to the project you are connected to.
const run = await client.interactions.execute(interactionId, {
    data: { object: "sky" }
});

console.log(run.result);
```

The response of the LLM will be:

```json
{
    "color": "blue"
}
```

## What's next?

Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further:

* [Go deeper into each endpoint of the API](/api/introduction)
* [Go deeper into using the CLI](/cli)