# CLI

The `klarety` command ships with the Python <Term id="sdk">SDK</Term>. It does what the SDK does from your terminal and prints JSON for piping.

## Install and sign in [#install-and-sign-in]

<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 [#install]

```bash
pip install klarety
klarety --help
```
</Step>
<Step>
### Store your key [#store-your-key]

Create an <Term id="api-key">API key</Term> in <AppLink to="settings.sdk-api" />, then:

```bash
klarety login "paste-your-key-here"
```

The key goes into your OS keychain, never a file. The CLI prints `key stored in the OS keychain`.
</Step>
<Step>
### Check it works [#check-it-works]

```bash
klarety sql "SELECT 1 AS ok"
```
</Step>
</Steps>

`klarety logout` forgets the stored key. Every command takes `--base-url` before the command name; it defaults to `https://api.klarety.ai`.

## Query [#query]

### `klarety sql` [#klarety-sql]

```bash
klarety sql "SELECT customer, SUM(amount) AS total FROM orders GROUP BY customer" --max-rows 50
```

| Argument | Meaning |
| --- | --- |
| `statement` | One SQL statement, in quotes. |
| `--max-rows` | Most rows to print, 1,000 by default. |

### `klarety tables` [#klarety-tables]

```bash
klarety tables
```

Lists the tables in your `default` schema.

## Load data [#load-data]

### `klarety ingest` [#klarety-ingest]

```bash
klarety ingest sales.csv --into sales --mode upsert --key order_id
```

Loads a local file into a table and prints the `run_id` and `state`.

### `klarety put` [#klarety-put]

```bash
klarety put q3-summary.pdf reports/q3 --name summary.pdf
```

Stores a file in a folder, by the folder's path as Object Storage shows it. `--name` sets its name there.

### `klarety load` [#klarety-load]

```bash
klarety load exports/daily --into daily_exports --mode append
```

Loads every file directly in the folder into a table.

### Load options [#load-options]

`ingest` and `load` share these options. See [Ingest data](/docs/developers/ingest) for what each mode does.

| Option | Meaning |
| --- | --- |
| `--into` | The table to load into. |
| `--schema` | The schema (`ingest` only), `default` by default. |
| `--mode` | `auto` (default), `append`, `upsert` or `replace`. |
| `--key` | A column that identifies a row. Repeat it for several columns. |
| `--force` | Load again a file that was already loaded. |

## Agents [#agents]

`klarety agent` works with the <Term id="agent">agents</Term> of one <Term id="project">project</Term>. Pass `--project <id>` before the action.

```bash
klarety agent --project <project-id> test daily-summary --input days=1
```

| Action | What it does |
| --- | --- |
| `check <name>` | Checks `agents/<name>.yaml` without saving it. |
| `save <name>` | Saves the YAML and its code as a draft. |
| `test <name>` | Saves, then runs the draft. Takes `--input name=value`, repeatable. |
| `publish <name>` | Saves, then asks a person to publish it. It goes live when they do. |
| `run <name>` | Runs the live version now. Takes `--input`. |
| `runs <name>` | Lists the agent's 20 latest runs. |
| `show <run_id>` | One run, step by step. |
| `result <run_id>` | What a run produced. |
| `stop <run_id>` | Stops a run. |
| `stats` | Runs per day: how many, how they ended, the cost. `--days`, 7 by default. |
| `rerun <run_id> --from-step <step>` | Runs again from one step, reusing the rest. |

In `--input`, `7` is read as a number and `true` as a boolean; anything else is text.

## Deploy [#deploy]

```bash
klarety deploy --project <project-id>
```

<Term id="deploy">Deploys</Term> the project's linked GitHub branch. With no linked repository, it sends the commit checked out in `--repo` (the current folder by default). It prints the `deploy_id`.

## Exit codes [#exit-codes]

| Code | Meaning |
| --- | --- |
| `0` | Done. |
| `2` | Refused or failed. The reason is printed on stderr. |
| `3` | Waiting for a person to approve. Not failed, but not done either. |

Output goes to stdout and messages to stderr, so `klarety sql "..." | jq` stays clean.

## Next steps [#next-steps]

- [Authentication](/docs/developers/authentication) for keys and rotation.
- [Agents and runs](/docs/developers/agents) for the same actions in Python.
- [Errors](/docs/developers/errors) for what each failure means.