The sokko CLI

Deploy a custom code agent from your repository, manage your agents, and move a local setup into Sokko from your terminal.

The sokko CLI is a command-line tool for people who would rather work in a terminal. It does three things: it deploys a custom code agent — an eve or flue project in your own GitHub repository — with one command, it lets you see and create agents without opening the dashboard, and it brings an agent you already run on your own machine into Sokko — keys, memory, and files in one command.

You do not need the CLI for most things. Everything except two jobs can also be done in the dashboard. The two it owns: scaffolding a custom code agent on your laptop, and reading your local agent folder to migrate it.

Install

npm i -g @sokko/cli
# or run it without installing
npx @sokko/cli --help

Requires Node 22 or newer.

You sign in with an API key from the dashboard. Create one under Settings → API Keys (owners and admins). Then:

sokko login          # paste your API key when prompted
sokko whoami         # confirm which org and role you are signed in as

Your key is saved at ~/.config/sokko/config.json (mode 0600). You can also pass it per command with --key, or set SOKKO_API_KEY in your environment.

See API keys for how to create and manage keys.

Deploy a custom code agent

An eve or flue agent is your own code. Sokko builds an image from your GitHub repository and runs it as an always-on agent, with channels, tools, and a model wired in.

Scaffold it

npx @sokko/cli init eve my-agent      # or: npx @sokko/cli init flue my-agent
cd my-agent && npm install

This copies the official example into my-agent and makes the first commit.

Push it to GitHub

gh repo create my-agent --private --source=. --push

No gh? Create an empty repository on GitHub, then git remote add origin https://github.com/<you>/my-agent.git && git push -u origin main.

Deploy it

sokko deploy

The first time, the CLI asks you to connect the Sokko GitHub App to your org (Settings → GitHub in the dashboard) so Sokko can read the repository, and which model the agent should use. Then it builds, rolls out, and prints the agent's address. Push a new commit and run sokko deploy again to ship it.

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

Other commands

sokko status                # the agent deployed from this repository
sokko instances ls          # list your agents: name, runtime, status, size
sokko instances create      # create a new agent, step by step
sokko migrate               # bring a local agent folder into Sokko

Point it at the right place

By default the CLI talks to https://sokko.ai. You rarely need to change this, but you can:

--api-url <url> or SOKKO_API_URL to change the server.
--key <key> or SOKKO_API_KEY to override the stored key.

Full command reference

Every command and flag, with examples.

Full command reference

On this page