CLI
Updated 2026-11-21
The jinn CLI publishes functions, manages persistent machines, starts runs and controls runs, from a terminal or from a script.
jinn login
jinn machines
jinn machine create [NAME] [--size s|m|l|xl] [--image IMG] [--idle 10]
jinn machine show|start|stop|snapshot|rm NAME|SLUG|mch_…
jinn machine resize NAME|SLUG|mch_… --size s|m|l|xl [--idle N]
jinn ssh NAME|SLUG|mch_…|run_… [--user USER] [-- SSH_ARGS…]
jinn ssh-keys
jinn ssh-key init [--name NAME] [--file PATH] [--no-config]
jinn ssh-key add [FILE] [--name NAME]
jinn ssh-key rm ssh_…
jinn functions
jinn function rm FUNCTION
jinn publish FILE
jinn run FUNCTION [--prompt TEXT] [--in DIR] [--out DIR] [--image IMG] [--env NAME=VALUE]… [--version N] [--webhook URL] [--ref REF] [--idempotency-key KEY] [--detach]
jinn exec RUN [--workdir DIR] [--timeout DURATION] -- COMMAND…
jinn cp PATH RUN:PATH
jinn cp RUN:PATH PATH
jinn shell RUN|MACHINE
jinn finish RUN [--failed REASON]
jinn runs [--function FUNCTION] [--state active|succeeded|failed]
jinn show RUN
jinn logs RUN [--follow]
jinn output RUN --out DIR
jinn images
jinn image rm IMAGE
jinn providers
jinn models VENDOR < vendor key
jinn provider NAME --vendor V --model M [--effort E] [--compact N] [--max-output N] < vendor key
jinn provider rm PROVIDER
jinn version
jinn update
jinn COMMAND … --json
FUNCTION is the id of a function, or its name if only one function has that name. jinn help shows the same list.
Add --json to a command to receive JSON. The CLI prints one JSON document. For a run or a log, it prints JSON lines while the events occur. Use Jinn from an agent shows the JSON.
| Exit status | Meaning |
|---|---|
| 0 | The command worked. |
| 1 | The run failed. |
| 2 | The command is not correct. |
| 3 | The API refused the request. The code of the error gives the cause. |
| 4 | A different error, for example from the network or a local file. |
jinn exec exits with the status of the remote command. If Jinn cannot run the command, jinn exec exits with 125.
Install
$ curl -fsSL https://github.com/usejinn/jinn-cli/releases/latest/download/install.sh | sh
The script comes from the latest GitHub release of the CLI. It downloads the build for your system from the same release. It compares the build with the SHA256SUMS file of the release. Then it puts jinn in /usr/local/bin. If it cannot write to that folder, it puts jinn in ~/.local/bin.
There are builds for Linux and macOS (x86-64 and ARM64), and for Windows (x86-64). If you have Go 1.25 or newer, you can also use go install usejinn.com/jinn@latest.
Update
$ jinn update
jinn v0.7.2 is the latest release.
jinn update replaces jinn with the latest release, if that release is newer. Before it changes anything, it checks the release:
- The release workflow signs each release with Jinn's release key.
jinn updatechecks the signature with the public key in the binary. A signature is valid for one version only. - The new build must match the signed
SHA256SUMSfile of the release. jinn updatenever installs an older version.
If a check fails, jinn does not change. With --json, jinn update prints the old version, the new version, and whether it updated.
If jinn is in a folder that you cannot write to, for example /usr/local/bin, use sudo jinn update. A build from source cannot update itself. Versions before v0.6.1 cannot update themselves: v0.6.0 checks a key that Jinn no longer uses, and older versions do not have jinn update. For these versions, run the install script again.
Verify
The release workflow in the public repository builds each release. No other system builds releases. Releases are immutable: after Jinn publishes a release, no file and no tag of the release can change. Each file has a build provenance attestation. To make sure that the workflow built a file from that repository:
$ gh attestation verify jinn-linux-amd64 --repo usejinn/jinn-cli
Each release has SHA256SUMS.sig, the signature that jinn update checks. The signature is over the line jinn-cli VERSION and the SHA256SUMS file. Jinn's release key is in release-key.pem in the repository:
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAKw/7F9tpDXShKIVNqxHN4d8aNqRVZ8Y/xUz76SeHL3s=
-----END PUBLIC KEY-----
To check a signature with OpenSSL 3:
$ v=v0.7.2 r=https://github.com/usejinn/jinn-cli
$ curl -fsSLO $r/releases/download/$v/SHA256SUMS -O $r/releases/download/$v/SHA256SUMS.sig -O https://raw.githubusercontent.com/usejinn/jinn-cli/$v/release-key.pem
$ { echo "jinn-cli $v"; cat SHA256SUMS; } > signed && base64 -d SHA256SUMS.sig > sig
$ openssl pkeyutl -verify -pubin -inkey release-key.pem -rawin -in signed -sigfile sig
Signature Verified Successfully
The build is reproducible. To build a release again and compare it:
$ git clone https://github.com/usejinn/jinn-cli && cd jinn-cli && git checkout v0.7.2
$ GOTOOLCHAIN=go1.25.12 CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w -buildid=" -o jinn-linux-amd64 .
$ sha256sum jinn-linux-amd64 # the same as in the release's SHA256SUMS
Authentication
jinn login prints a link and a code.
- Open the link.
- Make sure that the console shows the same code.
- Select the account.
- Approve the sign-in.
The CLI receives an admin key with the name of the machine. It saves the key in ~/.config/jinn/key. You can revoke this key in the console, as all other keys.
| Variable | Effect |
|---|---|
JINN_KEY | The CLI uses this key, not the saved key. Use it on servers and in CI. |
JINN_API | The CLI uses a different API address. |
NO_COLOR | The CLI prints without colour. If the output is not a terminal, the output is also plain. |
Run
$ jinn run pr-review --prompt "Review the change: a bulk discount for large orders." --in ./in --out ./result
run_7f933166d5deb68977b54366 queued · pr-review v4
run_7f933166d5deb68977b54366 running
agent bash {"command":"cp -a /workspace/in/repo /workspace/repo && cd /workspace/repo && git init -q && git apply /workspace/in/change.diff && cat README*","timeout_ms"…
agent bash {"command":"cd /workspace/repo && find . -maxdepth 3 -type f -not -path './.git/*' -print && cat /workspace/in/change.diff && python3 -m unittest","timeout_m…
bash → {"exit_code":1,"output":"./cart/__init__.py\n./cart/pricing.py\n./tests/test_pricing.py\n./tests/__init__.py\n./README.md\ndiff --git a/cart/pricing.py b/car…
agent bash {"command":"cd /workspace/repo && nl -ba cart/pricing.py && cat cart/__init__.py && nl -ba tests/test_pricing.py","timeout_ms":300000,"workdir":"/workspace"}
agent write {"content":"Request changes.\n\n- `cart/pricing.py:17` — The new bulk test fails. For 150 cents, this code rounds the discounted unit price to 142 cents, t…
agent write {"content":"[\n {\n \"path\": \"cart/pricing.py\",\n \"line\": 17,\n \"body\": \"The new bulk test fails. At 150 cents per item, this rounds the discounted u…
agent complete {}
✓ succeeded in 27.2s
result/comments.json 833 B
result/review.md 818 B
--inuploads a folder as the input of the run.--outdownloads the output folder when the run succeeds.- Without
--detach, the CLI follows the run of an agent. If the run fails, the CLI exits with status 1. --detachprints the id of the run and exits.--imageboots a different image.--envadds a variable. You can use it more than one time.--idempotency-keysends anIdempotency-Key. If a start of the function used the key in the last 24 hours, Jinn does not start a new run. The CLI then continues with that run. See Start a run one time.
A function without an agent has no prompt. jinn run waits until the run is ready, and then returns:
$ jinn run go-sandbox
run_5ab647d533bda87c1063b403 queued · go-sandbox v2
run_5ab647d533bda87c1063b403 ready · jinn finish run_5ab647d533bda87c1063b403 ends it
Control a run
$ jinn cp ./api.tar.gz run_5ab647d533bda87c1063b403:api.tar.gz
$ jinn exec run_5ab647d533bda87c1063b403 -- 'tar xzf api.tar.gz && cd api && go test -coverprofile=cover.out ./... && go tool cover -html=cover.out -o coverage.html'
ok example.com/api/http 0.001s coverage: 100.0% of statements
ok example.com/api/store 0.001s coverage: 100.0% of statements
$ jinn cp run_5ab647d533bda87c1063b403:api/coverage.html ./coverage.html
$ jinn finish run_5ab647d533bda87c1063b403
run_5ab647d533bda87c1063b403 succeeded
image img_1246e6c170ea4b93cf3ab52d
jinn execruns one command and prints its output while the command runs. If you give more than one word after--, the CLI quotes each word for bash. If you give one word, the CLI sends it as a command line.--timeouttakes a time, for example30m.jinn cpsends one file into the run, or downloads a file or a folder from the run. A relative path in the run starts at/workspace.jinn shellopens a terminal in a running run or machine: a login shell as root throughssh.usejinn.com. The CLI exits with the status of the shell. See Open a terminal.- The shell receives the size of your terminal, and each change of the size. If your terminal has no size, the shell uses
$LINESand$COLUMNS, or 24 rows and 80 columns. jinn finishends the run as succeeded. If the function saves an image, the CLI prints the id of the image.--failed REASONends the run as failed.
These commands work on all runs, with an agent or without one. See Commands.
Machines and SSH
$ jinn ssh-key init
✓ added MacBook-Pro (ssh_6a6e429442396cc363bf9d2d) SHA256:goW39hn/6OrV4nFHIvfqxu0GJ9VDYSR3nLdVCn6LAF0
✓ added Host ssh.usejinn.com to /Users/you/.ssh/config
$ jinn machine create dev --size m --idle 10
→ mch_2b6c8a7dc378fed83c5c84f9 swift-garnet
ssh swift-garnet@ssh.usejinn.com
$ jinn ssh dev
root@jinn:~#
jinn ssh-key initgenerates~/.ssh/id_ed25519if missing, uploads~/.ssh/id_ed25519.pub, and addsHost ssh.usejinn.comto~/.ssh/config. Pass--file PATHfor a custom key or--no-configto skip~/.ssh/config.jinn ssh NAME [--user USER]opens standardsshto a machine (waking it automatically if stopped) or an active run.jinn machine stop,jinn machine resize,jinn machine snapshot,jinn machine startandjinn machine rmmanage a machine's lifecycle. See Machines.
Functions
jinn functions lists the functions of the account. jinn function rm FUNCTION deletes a function, its versions and their secrets. Jinn refuses the delete while a run of the function is queued or running:
$ jinn run go-sandbox
run_83946e2027405a8165d2c0d1 queued · go-sandbox v2
run_83946e2027405a8165d2c0d1 ready · jinn finish run_83946e2027405a8165d2c0d1 ends it
$ jinn function rm go-sandbox
jinn: 409 runs_active: this function has runs that did not end: finish them or wait for them to end, then delete it
$ jinn finish run_83946e2027405a8165d2c0d1
run_83946e2027405a8165d2c0d1 succeeded
image img_db7cb890abefb5bf7e772f51
$ jinn function rm go-sandbox
See Delete a function.
Images
$ jinn images
img_1246e6c170ea4b93cf3ab52d run_5ab647d533bda87c1063b403 663.8 MB disk 51.5 GB 2026-10-14 09:50
debian-12-20260801-d780cfdb base 396.0 MB disk 2.2 GB 2026-10-13 21:02
$ jinn image rm img_1246e6c170ea4b93cf3ab52d
jinn images lists the images of the account, then the Jinn bases. See Images.
Runs
$ jinn runs --function support-triage
run_7c0ba925b3dfafd876b1b0ee support-triage v12 succeeded 2026-10-14 12:02 15.5s
run_22fa477e0afd7c3149b7573a support-triage v12 succeeded 2026-10-14 11:58 14s
run_90bdd4f8175861bad26e0e1b support-triage v11 succeeded 2026-10-14 11:43 13.7s
run_d63e4bc44d56e06564050468 support-triage v11 succeeded 2026-10-14 11:43 15.2s
jinn show RUN prints the full run as JSON. jinn logs RUN prints the log of the run, with one event on each line: the time, the kind and the fields of the event. With --follow, jinn logs prints the steps of the run until the run ends.
Providers
The CLI reads vendor keys from stdin, not from a flag. Thus your keys do not go into your shell history.
$ echo "$OPENAI_API_KEY" | jinn models openai
gpt-5.2 low,medium,high (default medium)
$ echo "$OPENAI_API_KEY" | jinn provider openai --vendor openai --model gpt-5.2 --effort medium
→ openai prv_8c1f04d2a7b93e650f1a2c47 v1 · use prv_8c1f04d2a7b93e650f1a2c47@latest in a function's provider
To publish a new version with a new key or model, use jinn provider again with the same name. The default of --compact is 200000 tokens.
jinn provider rm PROVIDER deletes a provider that no function uses. PROVIDER is its name or its id. See Providers.