Last updated 2026-10-25
Command line
kinsy is a small client over the API for terminals and agents. It signs you in once, then one command takes a brief and your documents to a downloaded, editable PowerPoint file. It needs Node 20 or newer.
npm install -g kinsy-cli # or run every command through: npx kinsy-cli …
kinsy login
kinsy create "Q3 board update for a 40-person SaaS company" --file q3-metrics.csv --slides 10 --wait --out board.pptx
The source is open (MIT) at github.com/kinsy-ai/kinsy-agents. If you are wiring Kinsy into an agent rather than typing commands yourself, start with Use Kinsy from your agent.
Signing in
kinsy login starts a device sign-in. The terminal prints a short code such as WXYZ-2345 and opens https://kinsy.ai/cli-auth; you confirm the code there while signed in, and the terminal receives its own API key. The key is labelled "CLI on hostname" in Settings → API keys, where you can revoke it at any time. Codes expire after ten minutes.
| Command | What it does |
|---|---|
kinsy login | Device sign-in; opens the browser for you. |
kinsy login --no-browser | Device sign-in; prints the link and the code for you to open yourself (remote shells, agents). |
kinsy login --key ksy_live_… | Stores a key you created in Settings after checking that it works. |
kinsy logout | Forgets the saved credentials on this machine. The key itself stays valid until you revoke it. |
kinsy me | Who is signed in, the plan, the credit balance, whether new decks carry a watermark, and which key is in use. |
Credentials live in ~/.config/kinsy/credentials.json, readable by you only (mode 0600 inside a 0700 directory). The key is never printed in full; you will only ever see ksy_live_…wxyz. For CI and agents, set KINSY_API_KEY in the environment instead; it takes precedence over the file.
Making a deck
kinsy create [brief] [options]
Put the brief first, in quotes: who the deck is for, what it must achieve, the three to five points it must make, the tone. Numbers belong in the sources, not the brief.
| Option | Meaning |
|---|---|
-f, --file <path...> | Documents to build from: PDF, Word-style documents, PowerPoint, spreadsheets, CSV, Markdown, plain text or images. Repeatable. Each file is extracted on the server and sent as a source. The brief is optional when at least one file is given. |
-n, --slides <n> | 4 to 25. Leave it out to let Kinsy choose (usually 10). |
--theme <id> | A theme from kinsy themes. |
--template <id> | A template id. |
--research auto|on|off | Whether to look things up on the web while planning. Default auto. |
--no-intake | Skip the clarifying questions Kinsy would otherwise answer for itself. |
-a, --answer key=value | Decide a clarifying question yourself, e.g. -a audience="the board". Repeatable. |
-w, --wait | Stay until the deck is done (one to two minutes). Progress prints on stderr. |
-o, --out <path> | Save the .pptx here once the deck is done (implies --wait). |
--idempotency-key <key> | Safe retries: the same key within 24 hours returns the first deck and charges nothing. |
--json | One JSON object on stdout, everything else on stderr. |
Without --wait you get the deck id straight away, to follow with kinsy status <id> --watch and fetch with kinsy get <id>. Credits are the same as in the web app: 40 for up to 10 slides, 60 for 11 to 16, 90 for 17 to 25, plus 10 per picture. When the balance is too low nothing is charged; the CLI prints the top-up link and exits with code 3.
Following, downloading, editing
| Command | What it does |
|---|---|
kinsy status <deck_id> [--watch] | Queued, running (phase, slides rendered, percent), done or error. --watch keeps polling until the deck is done. |
kinsy get <deck_id> [--pptx|--pdf|--png] [--out <path>] | Downloads the finished deck: the editable .pptx (default), the PDF, or a zip with one image per slide. Download links are fetched fresh every time. |
kinsy edit <deck_id> --slide <n> "<instruction>" | Rewrites one slide, counting from 1. 5 credits, plus 10 if the slide gets a new picture. If the instruction is too vague to carry out faithfully, Kinsy prints a question instead and charges nothing. |
kinsy themes | The theme ids you can pass to --theme. Needs no key. |
Every deck also has a web page, https://kinsy.ai/deck/<deck_id>, where you can review and edit it.
--json
Every command takes --json and then prints exactly one JSON object on stdout; progress and notes go to stderr. kinsy create --wait --out deck.pptx --json prints the final status with pptx_path, web_url and credits_charged added. Errors are the API's envelope on stdout: {"error": {"code", "message", "status", "checkout_url"?, "retry_after"?, "docs_url"?}}.
Exit codes
| Code | Meaning |
|---|---|
| 0 | done |
| 1 | unexpected error |
| 2 | not signed in, or the key was refused: run kinsy login |
| 3 | not enough credits; the top-up link is printed and nothing was charged |
| 4 | bad input, or the deck was not found |
| 5 | rate limited; the number of seconds to wait is printed |
| 6 | the deck failed to build, or --wait timed out |
| 7 | the server could not be reached, or answered with an error |
Environment
| Variable | Meaning |
|---|---|
KINSY_API_KEY | Use this key instead of the saved credentials. |
KINSY_API_BASE | Talk to another server (default https://kinsy.ai). |
KINSY_CONFIG_DIR | Where the credentials file lives (default ~/.config/kinsy). |
Limits
Builds, edits and extractions share the account's limits: 15 decks a day, 40 edits, intake calls or file extractions an hour, 120 requests a minute per key. Briefs up to 50,000 characters; up to 10 sources of 120,000 characters each; files up to 25 MB. The full list is on the overview.