Docs / Reference

CLI reference

Every sokie command and its options, generated from the CLI's own help.

Every command, as sokie <command> --help prints it. This page is written from the CLI's own help, so it always matches the version it was built from. sok is the same command, for short.

Every command

sokie init: Start a server from an OpenAPI or Swagger spec.
sokie check: Check the server in dir the way a deploy would, without deploying.
sokie tools: List the tools in tools/, or show one, with its effect and findings.
sokie call: Call one tool as an agent would, on sokie dev or a deploy.
sokie test: Run the cases in tests/ on sokie dev or a deploy.
sokie fmt: Write sokie.json the one way Sokie writes it.
sokie dev: Run the server locally on the real runtime, reloading on every edit.
sokie edit: Open a server's repository in your editor, with sokie dev running.
sokie login: Sign this computer in to Sokie.
sokie logout: Sign this computer out of Sokie.
sokie whoami: Show who this computer is signed in as.
sokie deploy: Deploy the server in dir and wait until it is live.
sokie deploys: Show what a deploy changed for agents, tool by tool.
sokie link: Deploy the server from its GitHub repository.
sokie secrets: List, set or remove the linked server's secrets.
sokie logs: Show the linked server's calls, as far back as your plan keeps them.
sokie audit: Show who changed what in your workspace over the last year.
sokie config: Show or shorten how long CLI sign-ins last.

Options every command takes

--json prints JSON for a script to read, instead of lines for a person. While the month's usage is past its alert or tool calls are stopped, a command that reaches the site also writes one JSON line to stderr, {"notice": {...}}, with the warning and a link to Billing; stdout keeps only the result.
--help, or -h, prints the command's help.

Commands that talk to a Sokie site take --site <url>, which defaults to https://sokie.sh or $SOKIE_SITE. You only need it for a site other than Sokie's own.

Exit codes

0: done.
1: it ran, and the answer is no, like errors in the server or a file that already exists.
2: it couldn't run as asked, like a missing or unknown argument.

sokie init

Start a server from an OpenAPI or Swagger spec.

sokie init <spec> [dir] [--name <name>]

Writes sokie.json, a committed copy of the spec (when it is a URL or lives
outside dir) and a file under tools/ for every operation, then checks the
result. An API key the spec asks for becomes "key": "perCaller", so each
person who connects brings their own. Nothing that exists is overwritten.

sokie check

Check the server in dir the way a deploy would, without deploying.

sokie check [dir]

Reads sokie.json, the spec and every tool, prompt and resource file, builds
the bundle a deploy would, and lists what is wrong. Exits 1 when there is an
error, so it can gate CI.

sokie tools

List the tools in tools/, or show one, with its effect and findings.

sokie tools [show <name>] [--all] [--unexposed] [--dir <dir>]

Reads the repository the way sokie check does, and lists each tool with the
effect it runs as (read, write, delete or external), the operation it calls,
and what check says about it. Long lists stop at 20; --all shows them all.

show <name>   One tool: its annotations, its inputs from the spec, and each
              finding with how to fix it.
--unexposed   Operations in the spec that no tool exposes.
--all         Every tool, however many.
--dir <dir>   The repository (default .).

sokie call

Call one tool as an agent would, on sokie dev or a deploy.

sokie call <tool> [--input '<json>'] [--yes] [--preview <n> | --production] [--server <slug>] [--dir <dir>] [--site <url>]

Calls the tool over MCP and prints what an agent would get back, then how
long it took. Exits 1 when the call fails.

By default the call goes to the sokie dev running for this checkout (start
it in another terminal first). --preview <n> calls the pull request's
preview and --production the live deploy, as you, with a token that lasts
five minutes; the call is logged with the client "Sokie test".

A tool that does more than read (write, delete or external) asks first,
because every target calls the real upstream. On a deploy, the effect comes
from this checkout when it is the server's linked repository; otherwise it
always asks.

A server with "discovery": "search" lists only searchTools,
getToolDefinition and useTool, so the tool is called through useTool; give
the tool's own name either way. searchTools and getToolDefinition can be
called by name too, to see what an agent finds.

--input <json>   The tool's arguments, as one JSON object (default {}).
--yes, -y        Don't ask. Needed when there is no terminal, as in a script.
--preview <n>    Call pull request n's preview deploy.
--production     Call the live deploy.
--server <s>     A server by slug, instead of the one this repository is linked to.
--dir <dir>      The repository (default .).
--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).

sokie test

Run the cases in tests/ on sokie dev or a deploy.

sokie test [--preview <n> | --production] [--all] [--server <slug>] [--dir <dir>] [--site <url>]

Runs each case in tests/<name>.json: one call, judged against its expect
(ok, match, items, bytes, under). Prints a line per case with how long it
took, then a summary. Exits 1 when any case fails.

By default the cases go to the sokie dev running for this checkout (start
it in another terminal first). --preview <n> runs them on the pull
request's preview and --production on the live deploy, as you, with a
token that lasts five minutes; the calls are logged with the client
"Sokie test".

A case runs only where its `on` says. Unset, that's everywhere for a read
tool, and dev and preview for anything above read, so nothing writes to
production unless its file says so. Cases call the real upstream.

--all            Print every passing case, not just the first 10.
--preview <n>    Run on pull request n's preview deploy.
--production     Run on the live deploy.
--server <s>     A server by slug, instead of the one this repository is linked to.
--dir <dir>      The repository (default .).
--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).

sokie fmt

Write sokie.json the one way Sokie writes it.

sokie fmt [dir] [--check]

Reorders sokie.json's keys to the schema's order with two-space indents, so a
change is always a small diff. With --check it writes nothing and exits 1 when
the file would change.

sokie dev

Run the server locally on the real runtime, reloading on every edit.

sokie dev [dir] [--port 8787] [--host 127.0.0.1] [--no-open]

Runs the server in dir (default: here) on the runtime Sokie deploys, reloads
it on every edit, and opens an inspector on the next port up. Secrets come
from .sokie/dev.env, which must be gitignored.

sokie edit

Open a server's repository in your editor, with sokie dev running.

sokie edit [<server-slug>] [--editor vscode|cursor|zed] [--dir <path>] [--no-dev] [--site <url>]

Finds the repository the server is linked to and uses your clone of it:
the folder you're in, or --dir. With neither, it clones into ./<name>, as
git clone would. Then it opens the folder in your editor and runs sokie dev
in it, reloading on every save. Open a pull request for a preview; merge
it to the default branch to deploy.

With no slug, the server this folder is linked to.

--editor <e>  vscode, cursor or zed, through its command on PATH. Without it,
              or when that command is missing, $VISUAL or $EDITOR.
--dir <path>  Your clone, or an empty folder to clone into.
--no-dev      Open the editor and stop; don't start sokie dev.
--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).

Sign this computer in to Sokie.

sokie login [--site <url>] [--no-browser]

Opens Sokie's consent page in your browser and signs this computer in.
The sign-in lasts as long as your account's CLI limits allow (Settings ›
CLI sign-ins); a later login on this computer is one click.

--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).
--no-browser  For SSH: print the address to open elsewhere, then paste back
              the address the browser lands on.

sokie logout

Sign this computer out of Sokie.

sokie logout [--site <url>]

Ends this computer's sign-in at the site and forgets its tokens.

--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).

sokie whoami

Show who this computer is signed in as.

sokie whoami [--site <url>]

Exits 1 when this computer isn't signed in to the site.

--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).

sokie deploy

Deploy the server in dir and wait until it is live.

sokie deploy [dir] [--create [--public] | --server <slug>] [--no-wait] [--site <url>]

Checks the repository the way the platform will, uploads its definition
files and waits for the deploy. The first deploy to a site says which server:

--create      Make a new server, named from sokie.json. Private unless --public.
--server <s>  Deploy to a server you already have, by its slug.

After that the repository is linked (in .sokie/servers.json, kept out of git).

In CI, set SOKIE_DEPLOY_KEY to a deploy key from the server's page instead
of signing in: it deploys that key's server, and nothing is written to disk.

--no-wait     Return once the deploy is queued.
--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).

sokie deploys

Show what a deploy changed for agents, tool by tool.

sokie deploys diff [<from>] <to> [--server <slug>] [--dir <dir>] [--site <url>]

Compares two deploys' bundles, by deploy number, and prints what an agent
sees differently: tools added, removed or renamed, descriptions, effects
raised or lowered, input schemas, response projections, operations, the
server's settings, prompts, resources and the runtime version.

With only <to>, a production deploy is compared with the production deploy
that went live before it, a preview with production as it is now, and a
first deploy lists every tool it added. Give <from> to compare any two.

--server <s>  A server by slug, instead of the one this repository is linked to.
--dir <dir>   The repository (default .), for its link.
--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).

sokie link

Deploy the server from its GitHub repository.

sokie link [<owner/repo> [--path <dir>]] | --remove [--server <slug>] [--site <url>]

Links the server to a GitHub repository. Pushes to its default branch then
deploy it, and each push gets a "Sokie" check. The Sokie GitHub App must be
installed on the repository; if it isn't, the browser says how.

With no repository, the browser opens the web app's link dialog after
GitHub: pick the account, the repository and the folder holding sokie.json
there, and this waits until the link is made.

--path <dir>  The directory holding sokie.json, for a monorepo (default: the root).
--remove      Unlink; pushes stop deploying.
--server <s>  A server by slug, instead of the one this directory is linked to.
--dir <dir>   The local repository (default .), for its link.
--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).

sokie secrets

List, set or remove the linked server's secrets.

sokie secrets list | set NAME | unset NAME [--server <slug>] [--dir <dir>] [--site <url>]

set reads the value without echoing it, or from a pipe:
  echo "$TASKS_API_KEY" | sokie secrets set TASKS_API_KEY
Values are never printed again. A change reaches the running server at once.

--server <s>  A server by slug, instead of the one this repository is linked to.
--dir <dir>   The repository (default .), for its link.
--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).

sokie logs

Show the linked server's calls, as far back as your plan keeps them.

sokie logs [--errors] [--tool <name>] [--limit 50] [--follow] [--server <slug>] [--dir <dir>] [--site <url>]

One line per call, oldest first: when, how it ended, the HTTP status, how
long it took and the tool, then for a failed tool its class and the
upstream's status, the client that called, and the preview it went to.
Last, which deploy production is on and since when. Arguments, results and
error messages are never kept. Calls are kept for your plan's days: 7 on
Hobby and pay as you go, 30 on Pro, 365 on Scale.

--errors       Only calls that didn't end ok.
--tool <name>  Only one tool's calls.
--limit <n>    How many of the latest calls to show (default 50, at most 200).
--follow, -f   Keep showing new calls as they arrive, within a few seconds.
--server <s>   A server by slug, instead of the one this repository is linked to.
--dir <dir>    The repository (default .), for its link.
--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).

sokie audit

Show who changed what in your workspace over the last year.

sokie audit [--type <kind>] [--server <slug>] [--limit 50] [--site <url>]

One line per change, oldest first: when, what changed, and who changed it,
a member (and whether from the CLI), a deploy key, GitHub, Sokie itself or
a connected client. Servers, deploys, secrets (names only), deploy keys,
GitHub links, connected clients, sign-ins and sign-outs are recorded.
Values of secrets, keys and tokens never are. Events are kept a year.

--type <kind>  Only one kind of change: servers, deploys, secrets, access, github, sign-ins, tools, workspace, billing.
--server <s>   Only one server's changes, by slug.
--limit <n>    How many of the latest changes to show (default 50, at most 500).
--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).

sokie config

Show or shorten how long CLI sign-ins last.

sokie config get | set <session.max-age|session.idle> <days> [--site <url>]

session.max-age  How long a sign-in lasts from approval, however often it's used.
session.idle     How long a sign-in may go unused.
Both apply to every computer signed in to your account. From the CLI they
can only be shortened; lengthen them in Settings › CLI sign-ins.

--site <url>  The Sokie site (default https://sokie.sh, or $SOKIE_SITE).