# Quickstart

In a few minutes you will have a <Term id="workspace">workspace</Term>, a first <Term id="project">project</Term>, a <Term id="table">table</Term> in <Term id="nexus">Nexus</Term> and the answer to your first <Term id="sql">SQL</Term> query.

## Before you start [#before-you-start]

All you need is an idea. Describe it to the AI in your project and start prompting.

Optional, whenever you want them:

- **GitHub**, to keep your code in your own repository.
- **Your own data**, such as a spreadsheet or CSV file.
- **For developers:** Python 3.11 or newer, and an API key from an owner or admin.

<Callout type="info" title="Developers need an admin">
Only workspace owners and admins can create API keys. If you are a member, ask an admin for a key.
</Callout>

## 1. Sign up and set up your workspace [#1-sign-up-and-set-up-your-workspace]

On first sign-in, Klarety walks you through a short welcome. Everything can be changed later in Settings.

<Steps>
<Step>
### Set up your profile [#set-up-your-profile]
Add your name, an optional picture and a title. This is how teammates see you.
</Step>
<Step>
### Name your workspace [#name-your-workspace]
Your projects, data and team live here. Use your company or team name; you can rename it any time.
</Step>
<Step>
### Connect GitHub [#connect-github]
Lets your projects push code and deploy on every push. Choose **Skip** to do it later from the Home page.
</Step>
<Step>
### Stay in the loop [#stay-in-the-loop]
Optional links to follow Klarety's releases. Continue when you are ready.
</Step>
<Step>
### Start your free trial [#start-your-free-trial]
Start the free trial of Pro to unlock projects, Studios and your data. The page shows how many days it lasts. Cancel any time before it ends.
</Step>
</Steps>

You land on **Home**. Its **Get started** checklist tracks the same steps: create your first project, connect GitHub, add your data, connect a tool and set up an agent.

<Screenshot src="/docs/_media/dashboard-home.png" alt="The Home page with the Get started checklist" />

## 2. Create your first project [#2-create-your-first-project]

A project holds your code, its <Term id="studio">Studio</Term> and its deploys. You need one to build, run agents or deploy.

<ForEveryone>
<Steps>
<Step>
### Start a new project [#start-a-new-project]
On <AppLink to="home" /> select **New project**, or open <AppLink to="projects.new" />.
</Step>
<Step>
### Name it [#name-it]
Type a project name. The default **Size** is plenty. Leave **How it runs** on the standard shared machine: if it is taken back, a new one starts on its own and no work is lost.
</Step>
<Step>
### Create it [#create-it]
Select **Create project**. The project opens and its Studio starts.

<Screenshot src="/docs/_media/projects-new.png" alt="The New project form with Project name, Size and How it runs" />
</Step>
</Steps>

For every option, see [Create a project](/docs/projects/create-a-project).
</ForEveryone>

<ForDevelopers>
Install the SDK and create an API key first (both in section 4 below), then:

```python
from klarety import Nexus

nx = Nexus.connect()  # reads KLARETY_API_KEY
project = nx.projects.create("My first project")
print(project)
```

For every option, see [Create a project](/docs/projects/create-a-project).
</ForDevelopers>

## 3. Add your data [#3-add-your-data]

Klarety turns spreadsheets and CSV files into tables in Nexus, your database.

<ForEveryone>
<Steps>
<Step>
### Open Add data [#open-add-data]
Go to <AppLink to="data" /> and choose **Turn a spreadsheet into a table**.
</Step>
<Step>
### Upload the file [#upload-the-file]
Pick your file. Klarety shows the **Columns found** and suggests a **Table name** you can change.
</Step>
<Step>
### Import [#import]
Select **Import**, then **Open table** to see your rows. The original file is also kept in a folder.
</Step>
</Steps>
</ForEveryone>

<ForDevelopers>
```python
from klarety import Nexus

nx = Nexus.connect()
run = nx.ingest("orders.csv", into="orders")
print(run.run_id, run.state)
print(nx.ingest_status(run.run_id).state)
```

Loading runs in the background; `ingest_status` tells you when it has finished. See [Ingest data](/docs/developers/ingest) for modes such as adding rows or updating rows by key.
</ForDevelopers>

<Screenshot src="/docs/_media/nexus-add-data.png" alt="Turn a spreadsheet into a table, with the columns found" />

## 4. Run your first query [#4-run-your-first-query]

<ForEveryone>
<Steps>
<Step>
### Open the SQL editor [#open-the-sql-editor]
Go to <AppLink to="data.sql" />. The side panel lists your tables; click a name to insert it.
</Step>
<Step>
### Write a query [#write-a-query]
```sql
SELECT * FROM orders LIMIT 100
```
Replace `orders` with your table's name.
</Step>
<Step>
### Run it [#run-it]
Select **Run** or press Cmd Enter (Ctrl Enter on Windows). Rows appear below the editor, with the row count.
</Step>
</Steps>
</ForEveryone>

<ForDevelopers>

<Callout type="info" title="Available on request">
The Klarety SDK and CLI are available on request. To request access for your workspace, [contact us](https://klarety.ai/contact).
</Callout>

<Steps>
<Step>
### Install the SDK [#install-the-sdk]
```bash
pip install klarety
```
</Step>
<Step>
### Create an API key [#create-an-api-key]
In the app, open <AppLink to="settings.sdk-api" /> and select **Create key**. After verifying it is you, give the key a **Name**, choose its **Access** and when it **Expires**, then copy it. It is shown only once.
</Step>
<Step>
### Connect and query [#connect-and-query]
```bash
export KLARETY_API_KEY="your-key"
```

```python title="first_query.py"
from klarety import Nexus

nx = Nexus.connect()
print(nx.account().credits)

result = nx.sql("SELECT * FROM orders LIMIT 100")
for row in result.rows:
    print(row)
```

`Nexus.connect` exchanges the key once for a one-hour token and renews it for you.
</Step>
<Step>
### Or use the command line [#or-use-the-command-line]
```bash
klarety login your-key
klarety sql "SELECT * FROM orders LIMIT 100"
```
`klarety login` stores the key in your operating system's keychain.
</Step>
</Steps>
</ForDevelopers>

## Check that it worked [#check-that-it-worked]

- Your project appears in <AppLink to="projects" />.
- Your table appears in **Nexus Lakehouse** under <AppLink to="data" />.
- Your query returns rows. If not, check the table name in the SQL editor's side panel.

## If something goes wrong [#if-something-goes-wrong]

<Accordions>
<Accordion title="The trial page would not open">
Choose **Try again**. If it still fails, refresh the page and start the step again.
</Accordion>
<Accordion title="I cannot create an API key">
Only owners and admins can manage API keys. Ask an admin to create one or to give you the role. A workspace has a limited number of active keys: revoke one you no longer use.
</Accordion>
<Accordion title="The query says the table does not exist">
Check the exact name in the SQL editor's side panel, or list tables with `nx.tables.list()` or `klarety tables`.
</Accordion>
<Accordion title="The result stops before the last row">
Results are capped by your plan. Add a `LIMIT` or `WHERE` clause to narrow the query. Your limits are in <AppLink to="settings.usage" />.
</Accordion>
</Accordions>

## Next steps [#next-steps]

- [Core concepts](/docs/get-started/concepts): what each part of Klarety is.
- [Your first project](/docs/guides/first-project): open the Studio and make your first change.
- [Ask your data a question](/docs/guides/first-query): go further with SQL.
- [Build your first agent](/docs/guides/first-agent): let Klarety do recurring work for you.