CLI
Sign in, query, load files, run agents and deploy from your terminal.
The klarety command ships with the Python . It does what the SDK does from your terminal and prints JSON for piping.
Install and sign in
Available on request
The Klarety SDK and CLI are available on request. To request access for your workspace, contact us.
Install
pip install klarety
klarety --helpStore your key
Create an in SettingsSDK & API, then:
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.
Check it works
klarety sql "SELECT 1 AS ok"klarety logout forgets the stored key. Every command takes --base-url before the command name; it defaults to https://api.klarety.ai.
Query
klarety sql
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 tablesLists the tables in your default schema.
Load data
klarety ingest
klarety ingest sales.csv --into sales --mode upsert --key order_idLoads a local file into a table and prints the run_id and state.
klarety put
klarety put q3-summary.pdf reports/q3 --name summary.pdfStores a file in a folder, by the folder's path as Object Storage shows it. --name sets its name there.
klarety load
klarety load exports/daily --into daily_exports --mode appendLoads every file directly in the folder into a table.
Load options
ingest and load share these options. See Ingest data 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
klarety agent works with the of one . Pass --project <id> before the action.
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
klarety deploy --project <project-id> 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
| 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
- Authentication for keys and rotation.
- Agents and runs for the same actions in Python.
- Errors for what each failure means.