--- title: "Krowk CLI reference — commands, flags and JSON output" canonical_url: "https://krowk.com/docs/cli" last_updated: "2026-09-02T08:08:02.763Z" meta: description: "Install the krowk CLI, push files and get permalinks. Every command, the push flags, the JSON envelope, --jq, breadcrumbs, exit codes and the environment variables." "og:description": "Install the krowk CLI, push files and get permalinks. Every command, the push flags, the JSON envelope, --jq, breadcrumbs, exit codes and the environment variables." "og:title": "Krowk CLI reference — commands, flags and JSON output" --- **Docs** # **The krowk CLI** One static Go binary, standard library only. Push a file, get a link, and read the whole command surface as JSON if you are a program. [github.com/krowkcom/cli](https://github.com/krowkcom/cli) [The full reference](https://krowk.com/docs) **MIT. Linux and macOS on amd64 and arm64, Windows on amd64.** **Install** ## **Three ways in.** The binary is the supported path in containers — agent containers rarely have Node, and the upload step is the last thing in a task. install — picks the platform, verifies checksums ``` $ curl -fsSL https://krowk.com/install | bash ``` or, if Node is already there ``` $ npx @krowk/cli push screenshot.png ``` or with a Go toolchain ``` $ go install github.com/krowkcom/cli/cmd/krowk@latest ``` ## Commands Ten top-level commands. The whole surface is also available as data — see below — so nothing here needs to be memorised. - `krowk push ` — upload files, one link each. - `krowk uploads` — list, show, attach and delete uploads. - `krowk runs` — start, finish, list and show runs. - `krowk claim ` — keep an anonymous upload past its 24-hour expiry. - `krowk auth` — log in, print the stored token, verify which key this is. - `krowk workspaces` — the stored keys, one per workspace, and which is the default. - `krowk config` — pin a repository, or the machine, to a workspace. - `krowk doctor` — version, connectivity, auth and the detected run context. - `krowk upgrade` — replace the binary with the latest release. - `krowk help` — this, or one command's own help. Wherever a command takes ``, `` or `--run` it takes the link as readily as the slug: paste the card URL or the CDN URL under it and the slug is read out of it. ## Push flags - `--caption` — what this one file shows. Repeatable, one per file, and it is what the paste block labels the image with. - `--title` — the title of the work, recorded on the run. Not the paste's label. - `--destination ` — github, gitlab, linear, notion, slack, basecamp, asana. Prints the form that tool renders and nothing else. - `--run` — attach to an existing run instead of opening one. - `--pull-request`, `--session`, `--reference` — work-level facts recorded on the run. The last is repeatable. - `--metadata key=value` — repeatable. Your value wins over a detected one, standard keys included. - `--repo`, `--commit`, `--agent` — override what would otherwise be detected from git and the environment. ## Output, for something that is not watching Output is human on a terminal and JSON when piped, so an agent capturing stdout gets structured data without asking. `--json` makes that a contract rather than a coincidence. One envelope for every command: `ok`, `data`, `paste` (both forms plus the destinations table), `summary` and `breadcrumbs`. agent shell ``` URL=$(krowk push shot.png --jq '.data.artifacts[0].url') BLOCK=$(krowk push shot.png --jq '.paste.markdown') ``` `--jq` filters that JSON in-process — jq is compiled in, so there is no binary to install and no pipe. It implies `--json`, and a string result prints unquoted, which is what makes the line above the whole ceremony. A bad expression fails as `bad_jq` before anything is sent; one that compiles and then does not fit the result fails as `jq_failed` afterwards, saying that the command itself succeeded. `krowk help --json` returns the entire command surface — commands, flags, types, defaults, environment variables. It is generated from the same catalogue that routes commands, so it cannot drift from what the binary does. An agent that has never seen the tool should read that rather than guess at a spelling. ## Breadcrumbs Every result ends with ready-to-run commands carrying that result's own slugs and tokens. A push prints the link to hand on; an anonymous push prints the claim command with the token already in it. Substitute any \ before running one — never paste a placeholder into a shell verbatim. ## Exit codes The class of failure is in the exit code, so a script can decide whether retrying is worth anything: - `0` ok · `1` bad command · `2` not found · `3` needs credentials - `4` refused, retrying will not help · `5` rate limited · `6` transfer failed, retry - `7` server error, retry · `8` gone, do not retry ## Configuration - `KROWK_TOKEN` — API token; wins over the credentials file. - `KROWK_WORKSPACE` — which stored key to use, as if by --workspace. - `KROWK_API_URL` — point at a self-hosted registry. - `KROWK_AGENT` — override the detected agent name. - `KROWK_MODEL` — name the model doing the work. ANTHROPIC\_MODEL is also read. - `KROWK_NO_UPDATE_CHECK` — never check for or mention new releases. Credentials from `krowk auth login` live in `~/.config/krowk/credentials.json` at mode 0600, one key per workspace. Which key a command uses resolves in order: `--workspace`, then `KROWK_WORKSPACE`, then `.krowk/config.json` at the git root, then `~/.config/krowk/config.json`, then whichever key logged in last. Commit the repository file and everyone who clones — person or agent — uploads to the right workspace without naming it. That file selects among keys already on the machine and never carries one itself. ## **The API is documented too.** The CLI is a convenience over a REST API you can drive with curl. Nothing here is a dependency you cannot walk away from. [The wire API](https://krowk.com/docs/api) [See the pricing](https://krowk.com/pricing)