Command reference

Install with npm i -g @sokko/cli (Node 22+). Run sokko --help any time.

Global options

These work on any command:

Option	Meaning
`--key <key>`	Use this API key instead of the stored one (or set `SOKKO_API_KEY`).
`--api-url <url>`	Talk to a different server (default `https://sokko.ai`, or `SOKKO_API_URL`).
`--yes`	Skip confirmation prompts, for scripts and CI.

The CLI honors NO_COLOR and drops to plain output when it is not attached to a terminal.

Builder agents

Use sokko builder status to list your authorized builder projects. Agents created through the builder retain their source and history in Sokko.

`sokko builder upgrade`

Upgrade an existing managed Eve project to Eve 0.67.2 and test the saved revision:

sokko builder upgrade PROJECT_ID \
  --question "What can you help me with?" \
  --expect "Answer consistently with the agent's instructions."

The upgrade preserves your instructions, tools, skills, settings, and existing agent. It supports the standard Eve 0.47.3 builder runtime. Modified runtime files, GitHub sources, and Flue require separate migrations.

The command prints a live test link and returns the agent's answer. Inspect the answer before recording an assessment with sokko builder assess. Use the printed --operation-id to resume an interrupted command. Upgrading does not deploy to production.

Older CLI versions can use the same server operation:

sokko builder change PROJECT_ID "/upgrade-runtime eve@0.67.2" \
  --question "What can you help me with?" \
  --expect "Answer consistently with the agent's instructions."

After the test passes, explicitly deploy the returned revision:

sokko builder publish PROJECT_ID --revision REVISION_ID \
  --user-request "Deploy the tested Eve upgrade to my existing agent."

The publication updates the same agent. Its saved dashboard messages remain available.

Custom code agents

An eve or flue agent is built from your own GitHub repository. Two commands take it from nothing to running: init, then deploy.

`sokko init`

Scaffold a new agent from the official example and make the first commit.

sokko init [eve|flue] [directory] [--template <owner/repo>[#ref]] [--force]

Flag / argument	Meaning
`framework`	`eve` or `flue`. Asked when omitted.
`directory`	Where to put it (default `my-<framework>-agent`). Must be empty unless `--force`.
`--template`	Scaffold from another GitHub repository instead of `tekiya-cloud/sokko-<framework>-example`.
`--force`	Scaffold into a directory that already has files.

It sets the package name to the directory name, runs git init with a first commit (skipped when git is missing or the directory is already inside a repository), and prints the next steps. For a private template repository, set GITHUB_TOKEN (or SOKKO_TEMPLATE_TOKEN) to a token that can read it. init does not need a Sokko login.

`sokko deploy`

Build and deploy the repository you are in. Run it after pushing to GitHub.

sokko deploy [--framework eve|flue] [--ref <branch|tag>] [--instance <id>] [--name <n>]
             [--no-wait] [--force] [--memory]
             [--byok | --sokko-credits] [--provider <p>] [--model <id>] [--api-key <k>]
             [--region us|eu] [--yes]

Flag	Meaning
`--framework`	Override what `package.json` says (`eve` dependency → eve, `@flue/runtime` → flue).
`--ref`	Branch or tag to build. Default: the branch you are on. Required on a detached HEAD.
`--instance`	Deploy to this agent. Needed only when several agents build from the same repository.
`--name`	Name for a new agent. Default: the repository name. It becomes the address `https://<name>.sokko.ai`.
`--no-wait`	Queue the build and return at once.
`--force`	Rebuild even when the ref already points at the deployed commit.
`--memory`	Turn on the memory add-on for a new agent (paid).
`--byok`	New agent: bring your own key. Needs `--api-key` and `--provider`.
`--sokko-credits`	New agent: use a Sokko-managed model. Needs `--model`.
`--provider`	For BYOK: `anthropic`, `openai`, `openrouter`, and others.
`--model`	Model id.
`--api-key`	For BYOK: your provider key.
`--region`	`us` or `eu` (Sokko credits).

What happens, in order:

It reads the framework from package.json and the origin remote from git (https://github.com/… and git@github.com:… both work). It warns when you have uncommitted changes or unpushed commits — Sokko builds what is on GitHub.
It checks that your org's Sokko GitHub App can see the repository. If not, it prints where to connect it (Settings → GitHub) and waits for you to press Enter to check again.
It finds the agent deployed from this repository. If there is one, it points it at the branch and queues a rebuild. If there is none, it creates one and asks which model to use. If the branch already points at the deployed commit, nothing is built.
It waits and shows progress: building the image, then rolling out. When the agent is live it prints the agent URL and the dashboard link. If the build fails it prints the latest error messages and exits with status 1.

Connect Slack or Telegram from the agent's Channels tab in the dashboard.

`sokko status`

Show the agent deployed from the repository you are in: status, source (repository, branch, commit), the last build, and the URLs.

sokko status [--instance <id>]

Account

Validate an API key and store it at ~/.config/sokko/config.json.

sokko login
sokko login --key sk_live_xxx      # non-interactive

`sokko logout`

Remove the stored credentials.

`sokko whoami`

Show the organization and role you are signed in as.

Agents

`sokko instances ls`

List your agents with their name, runtime, status, and size.

sokko instances ls

`sokko instances create`

Create a new agent. Run it with no flags for a step-by-step prompt, or pass flags to go straight through.

sokko instances create [--runtime <r>] [--name <n>] [--slug <s>]
                       [--repo <owner/repo>] [--ref <ref>]
                       [--byok | --sokko-credits] [--provider <p>] [--model <id>]
                       [--api-key <k>] [--region us|eu] [--memory]
                       [--subscribe-memory monthly|annual] [--yes]

Flag	Meaning
`--runtime`	`openclaw`, `hermes`, `eve`, or `flue`. (Cursor agents are created from the dashboard.)
`--name`	A name for the agent. It becomes the web address `https://<name>.sokko.ai`.
`--repo`	For `eve` / `flue`: the GitHub repository to build, as `owner/repo`. Asked from your connected repositories when omitted.
`--ref`	For `eve` / `flue`: the branch or tag to build (default: the repository's default branch).
`--byok`	Bring your own key. Needs `--api-key` and `--provider`.
`--sokko-credits`	Use a Sokko-managed model. Needs `--model`.
`--provider`	For BYOK: `anthropic`, `openai`, `openrouter`, and others.
`--model`	For Sokko credits: the model id to run.
`--api-key`	For BYOK: your provider key.
`--region`	`us` or `eu`.
`--memory`	Turn on the memory add-on (paid; asks first).

The machine size is set by your plan, not a flag. The CLI shows it read-only after the agent is created; change tiers from Billing in the dashboard. eve and flue agents always need a model, and their repository must be visible to your org's Sokko GitHub App.

`sokko migrate`

Bring a local agent folder into a Sokko agent — secrets, memory, and files. This one has its own page:

Migrate a local agent

The full walkthrough, including a dry run that writes nothing.

sokko migrate [--instance <id>] [--runtime <r>] [--path <dir>] [--dry-run]
              [--on-conflict skip|replace] [--only secrets,memory,files]
              [--create] [--subscribe-memory monthly|annual] [--yes]

Running unattended

For scripts and CI, pass a key and skip prompts:

SOKKO_API_KEY=sk_live_xxx sokko instances ls
SOKKO_API_KEY=sk_live_xxx sokko deploy --yes            # redeploy the pushed branch
SOKKO_API_KEY=sk_live_xxx sokko deploy --yes --sokko-credits --model anthropic/claude-3.5-sonnet
sokko migrate --instance <id> --yes --key sk_live_xxx

Migrate a local agent

On this page