Kosuke CLI
Install the Kosuke CLI to start chat sessions, follow turns and manage projects from your terminal or a script. You need Node.js 22.18 or later. Install it with npm, sign in with an API key, and every API command that returns a body prints JSON you can pipe into jq.
Install
npm install -g @kosuke-ai/cli
kosuke --version
Sign in
- Create an API key in Settings > Your Account > API keys. See Authentication.
- Run
kosuke auth loginand paste the key when it asks. What you type stays hidden. - Kosuke checks the key and saves it. It prints a line such as
Logged in to https://app.kosuke.ai; member of 2 workspaces. API key saved to /home/you/.config/kosuke/credentials.json.
kosuke auth status shows where the key comes from and whether Kosuke accepts it. kosuke auth logout deletes the stored key.
In CI or any script that runs without a person, skip the login. Set the KOSUKE_API_KEY environment variable to the key, or pass --api-key <token> to any command. A key from a flag or the environment wins over the stored one.
Inside a chat sandbox, where the credential is a sandbox agent token, the tree narrows to the operations that token may call. The same holds in a Cron Run, where the credential is the run's own key. The sandbox also has ksb integrations, which lists and runs the tools of the workspace's connected integrations: list takes --toolkit <slug> and --search <text>, and describe <name> reads one tool by name.
The MCP server does not need this key: your agent's client signs you in through the browser instead, though it also accepts an API key as a bearer token.
Your first commands
# 1. Find the project's id.
kosuke projects list | jq '.data[] | {id, name}'
# 2. Start a chat session, and note its session id and job id.
kosuke sessions create <projectId> --content "Fix the typo in the pricing page footer" \
| jq '.data | {sessionId: .session.id, jobId: .chatJobId}'
# 3. Follow the turn until it ends, printing what the agent says.
kosuke sessions watch <projectId> <sessionId> <jobId> \
| jq -r 'select(.type == "message") | .data.text'
sessions create starts the session right away. To add it to the Backlog instead, add --status backlog, then start it later with kosuke sessions activate.
How commands work
- Ids are positional arguments, in the order the help shows, such as
kosuke sessions get <projectId> <sessionId>. - Request fields are flags, such as
--title,--contentor--exclude-archived. --body '<json>'sends a whole request as JSON.--body-file <path>reads it from a file, and--body-file -reads it from stdin. A few commands, such asprojects env-vars add, take only a whole body.--attach <path>attaches a file. Repeat it for several files.sessions create,sessions send,sessions edit-prompt,sessions queue update,deploy runanddeploy queue updatetake files.- Every API command that returns a body prints JSON to stdout, with the result under
data; one whose request answers 204 prints nothing. Errors go to stderr, and the command exits with 1. --helpworks at every level.kosuke sessions --helplists the group's commands, andkosuke sessions send --helplists that command's flags.
Command reference
The tables list the main commands, not every one. kosuke <group> --help lists every command in a group.
auth
| Command | Arguments | What it does |
|---|---|---|
auth login | none | Store an API key after checking it works |
auth status | none | Show where the key comes from and whether Kosuke accepts it |
auth logout | none | Delete the stored key |
projects
| Command | Arguments | What it does |
|---|---|---|
projects list | none | List the projects you can reach, across every workspace |
projects get | <projectId> | Read one project |
projects create | none | Import a GitHub repository as a project |
projects update | <projectId> | Rename a project |
projects delete | <projectId> | Delete a project and everything it owns. Admins only |
projects branches | <projectId> | List the repository's branches |
projects skills | <projectId> | List the skills the agent can run in the project, for one provider |
projects labels | <projectId> | List the project's Session Labels |
projects settings get | <projectId> | Read setup commands, services, environment and sandbox size |
projects settings update | <projectId> | Change setup commands, branches, working directory or sandbox size |
projects settings import | <projectId> | Replace services and environment from a kosuke.config.json file |
projects qa-guide set | <projectId> | Save the project's QA Guide from --content |
projects services list | <projectId> | List the services in the order they start |
projects services add | <projectId> | Add a service |
projects services update | <projectId> <serviceId> | Change a service |
projects services remove | <projectId> <serviceId> | Remove a service |
projects env-vars add | <projectId> | Add environment variables |
projects env-vars remove | <projectId> | Remove environment variables |
sessions
| Command | Arguments | What it does |
|---|---|---|
sessions list | <projectId> | List a project's chat sessions |
sessions all | none | List sessions across every workspace. --needs-you keeps the ones waiting on a person |
sessions search | none | Search sessions by title |
sessions get | <projectId> <sessionId> | Read a session with its latest turn and pull request |
sessions create | <projectId> | Start a session, or add one to the Backlog with --status backlog |
sessions activate | <projectId> <sessionId> | Start a Backlog session |
sessions update | <projectId> <sessionId> | Change the title, status, model, Assignee or priority |
sessions delete | <projectId> <sessionId> | Delete a session |
sessions labels set | <projectId> <sessionId> | Replace the session's Session Labels |
sessions labels edit | <projectId> <sessionId> | Add and remove Session Labels, leaving the rest |
sessions edit-prompt | <projectId> <sessionId> | Rewrite a Backlog session's prompt and attachments |
sessions title-generate | <projectId> <sessionId> | Suggest a title for a Backlog session |
sessions send | <projectId> <sessionId> | Send a message. It starts a turn, or waits Up next |
sessions messages | <projectId> <sessionId> | Read the whole conversation |
sessions watch | <projectId> <sessionId> <jobId> | Follow a turn until it ends |
sessions runtime-command | <projectId> <sessionId> | Run /clear or /compact |
sessions jobs list | <projectId> <sessionId> | List the session's turns |
sessions jobs get | <projectId> <sessionId> <jobId> | Read one turn's status |
sessions jobs cancel | <projectId> <sessionId> <jobId> | Stop a running turn |
sessions queue list | <projectId> <sessionId> | List the messages Up next |
sessions queue update | <projectId> <sessionId> <queuedMessageId> | Edit your own message Up next |
sessions queue move | <projectId> <sessionId> <queuedMessageId> | Move your own message within Up next |
sessions queue steer | <projectId> <sessionId> <queuedMessageId> | Steer your own message into your running turn |
sessions queue delete | <projectId> <sessionId> <queuedMessageId> | Delete a message Up next |
sessions queue resume | <projectId> <sessionId> | Resume a paused Up next |
sessions comments list | <projectId> <sessionId> | List the session's comments |
sessions comments add | <projectId> <sessionId> | Comment on the session, or reply to a comment |
sessions comments update | <projectId> <sessionId> <commentId> | Edit your own comment |
sessions comments delete | <projectId> <sessionId> <commentId> | Delete your own comment |
sessions diff files | <projectId> <sessionId> | List the files the session's branch changes |
sessions diff patch | <projectId> <sessionId> | Read the changes as patches |
sessions diff commits | <projectId> <sessionId> | List the commits on the session's branch |
sessions diff comments list | <projectId> <sessionId> | List the line comments on the changes |
sessions diff comments add | <projectId> <sessionId> | Comment on a range of lines |
sessions diff comments update | <projectId> <sessionId> <commentId> | Edit your own line comment, or resolve or reopen any |
sessions diff comments delete | <projectId> <sessionId> <commentId> | Delete your own line comment |
sessions files list | <projectId> <sessionId> | List the files in the session's sandbox |
sessions files get | <projectId> <sessionId> | Read one file. Wake the sandbox first |
sessions files write | <projectId> <sessionId> | Write one file |
sessions git state | <projectId> <sessionId> | Read whether the sandbox has uncommitted changes, unpushed commits, or commits ahead of the base branch |
sessions git commit-message | <projectId> <sessionId> | Draft a commit message for the changes |
sessions git commit | <projectId> <sessionId> | Commit the changes |
sessions git push | <projectId> <sessionId> | Push the session's branch to GitHub |
sessions artifacts list | <projectId> <sessionId> | List the session's artifacts |
sessions artifacts get | <projectId> <sessionId> <artifactId> | Read one artifact |
deploy
| Command | Arguments | What it does |
|---|---|---|
deploy run | <projectId> | Start a Deploy, or answer the deploy agent |
deploy cancel | <projectId> | Stop the running Deploy |
deploy list | <projectId> | List the project's Deploys |
deploy messages | <projectId> | Read the Deploy Chat and the current Deploy status |
deploy set-model | <projectId> | Pick the deploy agent's model |
deploy queue list | <projectId> | List the Deploy Chat messages Up next |
deploy queue update | <projectId> <queuedMessageId> | Edit your own message Up next |
deploy queue move | <projectId> <queuedMessageId> | Move your own message within Up next |
deploy queue steer | <projectId> <queuedMessageId> | Steer your own message into the running deploy turn. Claude deploys only |
deploy queue delete | <projectId> <queuedMessageId> | Delete a message Up next |
deploy queue resume | <projectId> | Resume the Deploy Chat's paused Up next |
preview
| Command | Arguments | What it does |
|---|---|---|
preview get | <projectId> | Read the preview addresses of the main preview, or of a session with --session-id |
preview health | <projectId> | Read the health of each service behind a preview |
preview reset | <projectId> | Restart a preview's services in place |
preview share get | <projectId> | Read a preview's share link, if it has one |
preview share create | <projectId> | Create a preview's share link |
preview share delete | <projectId> | Revoke a preview's share link |
preview shared | <slug> | Open a share link. Needs no API key |
preview shared artifact | <slug> <artifactId> | Read an artifact behind a share link. Needs no API key |
crons
| Command | Arguments | What it does |
|---|---|---|
crons list | <workspaceId> | List a workspace's crons. --project keeps the ones that include a project |
crons get | <workspaceId> <cronId> | Read one cron with its projects |
crons create | <workspaceId> | Create a cron. --project names a project and repeats for several |
crons update | <workspaceId> <cronId> | Change a cron. --project replaces its projects, --no-enabled pauses it and --enabled resumes it |
crons delete | <workspaceId> <cronId> | Delete a cron with its runs, transcripts and Artifacts |
crons run | <workspaceId> <cronId> | Fire a cron once now, in every project that is not paused or in the ones --project names |
crons projects resume | <workspaceId> <cronId> <projectId> | Resume one project that five failed runs in a row paused |
crons runs list | <workspaceId> <cronId> | List a cron's runs. --project and --status filter them and repeat for several |
crons runs get | <workspaceId> <cronId> <runId> | Read one run with its Reply and the sessions it filed |
crons runs messages | <workspaceId> <cronId> <runId> | Read the Cron Agent's transcript of one run |
crons runs artifacts list | <workspaceId> <cronId> <runId> | List the Artifacts a run published |
crons runs artifacts get | <workspaceId> <cronId> <runId> <artifactId> | Read one Artifact of a run |
crons runs cancel | <workspaceId> <cronId> <runId> | Stop a run that is still going |
workspaces
| Command | Arguments | What it does |
|---|---|---|
workspaces list | none | List the workspaces you belong to |
workspaces get | <workspaceId> | Read a workspace and your role in it |
workspaces members | <workspaceId> | List members and pending invitations |
workspaces credits | <workspaceId> | Read the credit balance and limit |
workspaces usage | <workspaceId> | Read sandbox usage by day and by project |
workspaces sandbox-limit | <workspaceId> | Read how many sandboxes may run at once, and which are running |
workspaces stop-sandboxes | <workspaceId> | Pause the sandboxes of the sessions you name |
workspaces access-status | <workspaceId> | Read which providers you, or the workspace, can run |
workspaces ai-provider get | <workspaceId> | Read the workspace's Credentials, with secrets masked |
workspaces ai-provider set | <workspaceId> | Store or switch workspace Credentials. Admins only |
workspaces ai-provider remove | <workspaceId> | Remove one set of workspace Credentials. Admins only |
workspaces ai-provider usage claude | <workspaceId> | Read the workspace Claude login's usage |
workspaces ai-provider usage codex | <workspaceId> | Read the workspace Codex login's usage |
workspaces ai-provider usage coding-plan | <workspaceId> | Read the workspace GLM Coding Plan's usage |
workspaces ai-provider usage kimi-code | <workspaceId> | Read the workspace Kimi Code key's usage |
workspaces provider-login claude start | <workspaceId> | Start a Claude login for the workspace. Admins only |
workspaces provider-login claude complete | <workspaceId> | Finish a Claude login with the code from the browser. Admins only |
workspaces provider-login codex start | <workspaceId> | Start a Codex login for the workspace. Admins only |
workspaces provider-login codex complete | <workspaceId> | Finish a Codex login once the code is approved. Admins only |
workspaces skills list | <workspaceId> | List the workspace's Custom Skills |
workspaces skills get | <workspaceId> <skillId> | Read one Workspace Skill with its files |
workspaces skills create | <workspaceId> | Add a custom skill from its files. Admins only |
workspaces skills update | <workspaceId> <skillId> | Turn a skill on or off, or replace a custom skill's files. Admins only |
workspaces skills delete | <workspaceId> <skillId> | Delete a Custom Skill and its files. Admins only |
workspaces plugins list | <workspaceId> | List the plugins the official marketplaces offer, and which are on |
workspaces plugins update | <workspaceId> <pluginId> | Turn a Workspace Plugin on or off. Admins only |
workspaces integrations list | <workspaceId> | List the workspace's integrations with their status |
workspaces integrations get | <workspaceId> <toolkit> | Read one integration by toolkit slug, such as sentry |
workspaces integrations remove | <workspaceId> <toolkit> | Disconnect an integration. Admins only |
workspaces integrations slack get | <workspaceId> | Read the Slack integration |
workspaces getting-started get | <workspaceId> | Read the Get started guide and which steps are done |
workspaces getting-started update | <workspaceId> | Dismiss the Get started guide |
user
| Command | Arguments | What it does |
|---|---|---|
user profile | none | Read your account and preferences |
user subscriptions get | none | Read your Claude, Codex, GLM Coding Plan and Kimi Code Subscriptions and your Default Model |
user subscriptions delete | <provider> | Disconnect your Subscription for one provider |
user subscriptions usage | none | Read your Subscription's usage |
user subscriptions set-key | <provider> | Connect your GLM Coding Plan or Kimi Code with its key |
user subscriptions set-default-model | none | Save your Default Model |
user subscriptions login claude start | none | Start connecting your Claude Subscription |
user subscriptions login claude complete | none | Finish connecting it with the code from the browser |
user subscriptions login codex start | none | Start connecting your Codex Subscription |
user subscriptions login codex complete | none | Finish connecting it once the code is approved |
user skills list | none | List your Personal Skills |
user skills get | <skillId> | Read one Personal Skill with its files |
user skills create | none | Add a Personal Skill from its files |
user skills update | <skillId> | Turn a Personal Skill on or off, or replace its files |
user skills delete | <skillId> | Delete a Personal Skill |
user plugins list | none | List the plugins you can turn on for yourself |
user plugins update | <pluginId> | Turn a Personal Plugin on or off |
github, models, activity and agent
| Command | Arguments | What it does |
|---|---|---|
github status | none | Read your GitHub Connection |
github repositories | none | List the repositories the Kosuke App can reach through your connection |
models list | none | List the models a chat session can use, as the values --model takes |
activity list | none | List Activity across your workspaces. --unseen keeps only New events |
agent summary | none | Print a short digest of what needs you, for an agent to read |
Follow a turn with sessions watch
kosuke sessions watch follows one turn as it runs, so a script does not have to poll. The job id is the chatJobId that sessions create and sessions send print when they start a turn. A send that waits Up next prints a queuedMessageId instead. Each event is one JSON line on stdout. Messages meant for a person go to stderr.
If the connection drops, watch reconnects and picks up where it left off. When the turn ends, a last watch.links line carries the session, preview and pull request links. If some events could not be read, a watch.status line says "complete": false.
| Flag | What it does |
|---|---|
--timeout <seconds> | Stop waiting after this many seconds and exit with 124 |
--type deploy | Follow a Deploy turn instead. The job id is the activeStreamId that kosuke deploy messages prints |
| Exit code | Meaning |
|---|---|
| 0 | The turn ended, or stopped to ask you a question |
| 1 | The turn failed or was stopped |
| 3 | The API key was refused |
| 4 | The project, session or turn was not found |
| 124 | --timeout passed before the turn ended |
Use it with your coding agent
The MCP server covers most of what a coding agent needs. A few things only the CLI does:
- Attach a file, with
--attach. - Send the deploy agent a message with files attached, with
kosuke deploy run <projectId> --content "…" --attach <path>. - Print every event of a turn as it happens, with
kosuke sessions watch.
Give your agent a digest
kosuke agent summary prints a digest of about 1,500 tokens for an agent to read. It lists:
- the chat sessions that need you
- your connected Subscriptions and their usage, and with
--workspacethat workspace's AI providers too - your oldest New Activity events, one line each
- the workspaces it read
It marks seen only the events it prints. The rest stay New for kosuke activity list --unseen. Add --workspace <id> to cover one workspace, or --peek to mark nothing seen.
To have your coding agent start from it, paste this line into your AGENTS.md or CLAUDE.md:
Before you answer anything about my Kosuke work, run `kosuke agent summary --peek` and read what it prints.
Configuration
| Setting | Flag | Environment variable | Default |
|---|---|---|---|
| API key | --api-key <token> | KOSUKE_API_KEY | The key kosuke auth login stored |
| Kosuke address | --api-url <url> | KOSUKE_API_URL | https://app.kosuke.ai |
| Config folder | none | KOSUKE_CONFIG_DIR | $XDG_CONFIG_HOME/kosuke, else ~/.config/kosuke. On Windows, %APPDATA%\kosuke |
A flag wins over its environment variable, and both win over the stored key. The stored key is credentials.json in the config folder, readable only by you.
Update
Run the install command again, then check the version:
npm install -g @kosuke-ai/cli
kosuke --version