CLI reference

Every ciresk dev command with its arguments, flags, defaults and exit codes. ciresk dev --help and ciresk dev <command> --help print the same from the CLI itself.

Most commands act on the session of the worktree you run them in, so run them from inside a checkout. Human output goes to stdout and progress lines to stderr; with --json the command prints one JSON document instead. Answers name next: the exact command to run after it.

Command index

Command	What it does
`up`	Start this worktree's session, or return the one already running
`down`	End this worktree's session
`stop`	Stop a remote session and keep it: files checkpointed, compute released
`start`	Start a stopped remote session again from its checkpoint
`schedule show`	A session's or template's autostart schedule
`schedule set`	Have a stopped remote session ready at a local time on chosen days
`schedule clear`	Remove a schedule
`status`	Services, generations, health, diagnostic counts and clients
`wait`	Wait until every workspace service serves a generation
`sync`	Whether the session has your local tree
`open`	Open the session's web URL in the browser
`ssh`	A shell in the session over SSH
`ssh-config`	Write the managed block in `~/.ssh/config`
`code`	Open VS Code, Cursor, Windsurf or JetBrains Gateway on the session
`exec`	Run a command in a session container
`logs`	A service's last log lines
`restart`	Restart one service
`diagnostics`	Compile and type errors as data
`reset`	Put the session's data back to its seed
`login`	Take a test identity's cookies, or end its login
`evidence`	Screenshot, console and failed requests of a page, as a bundle
`search`	Search the session's code
`checkpoint`	A remote session's workspace as a tree root
`push`	A remote session's workspace as a commit on its own branch
`share`	Give a member view or use of your session, revoke it, list members
`watch`	Follow what happens in the session, read-only
`attach`	Grant this device a session another device created
`init`	Write a template from a compose file or a devcontainer
`templates publish`	Publish a template as a version of the organization
`templates promote`	Make a version the active one for a repository
`templates list`	The organization's template versions
`secrets list`	The organization's session secrets, never a value
`secrets set`	Create or replace a secret, value from stdin
`secrets rm`	Delete a secret
`dotfiles show`	Your dotfiles repository
`dotfiles set`	Set your dotfiles repository
`dotfiles rm`	Remove your dotfiles repository
`policy show`	The policy and path view that apply to you
`policy set`	Write a new policy version from a file
`policy preset`	Write a new policy version from a preset
`usage`	Your use today and the organization's this month, against the budget
`kill`	Stop a session, an owner's sessions or every session now
`connections`	The connection log
`egress`	The session's egress decisions
`admin enrol-worker`	Issue or revoke a worker host's enrolment secret
`admin drain-worker`	Drain a worker host, or undrain it
`mcp`	The stdio MCP server with the `dev_session_*` tools
`mcp browser`	MCP stdio to the session's browser
`mcp next`	MCP stdio to a service's Next.js dev MCP endpoint
`needs`	What the session needs from its person
`needs raise`	Tell your person you are blocked on them
`needs reply`	Answer a need
`needs dismiss`	Close a need unanswered
`doctor`	Check this machine
`setup`	Set up the `.localhost` resolver or the agent integration
`ci`	The CI jobs verified on the session's tree
`ci record`	Attach a finished CI job to the session

Global flags and environment

These flags work on every command, before or after it.

Flag	Type	Default	Meaning
`--json`	switch	off	Print one JSON envelope on stdout: `schema_version`, `command`, `request_id`, `data` on success or `error` (an RFC 9457 problem with `code` and `next`) on failure, `budget`, `next` and `truncated`. The same envelope `ciresk ci` prints.
`-q`, `--quiet`	switch	off	No progress lines on stderr.
`--api-url <URL>`	string	`https://api.<region>.ciresk.com`	The control plane, e.g. `https://api.eu.ciresk.com`.
`--org <ORG>`	string	the stored credential's	The organization whose credential to use when several are stored.
`--region <REGION>`	string	`eu`	`eu` or `us`.
`--profile <NAME>`	string	the default profile	The keychain profile whose credential to use, as stored by `ciresk ci auth login --profile <NAME>`.
`-h`, `--help`	switch		Print help.
`-V`, `--version`	switch		Print the version.

ciresk dev signs in with the credential ciresk ci auth login stored in the OS keychain; one sign-in covers both. An API key works too (see API keys).

Variable	Meaning
`CIRESK_DEV_TOKEN`, `CIRESK_TOKEN`	A key to use when the keychain holds no credential for the account, in that order.
`CIRESK_DEV_API_URL`, `CIRESK_API_URL`	The control plane, below `--api-url`, in that order.
`CIRESK_REGION`	The region, below `--region`.
`CIRESK_ORG`	The organization, below `--org`.
`CIRESK_DEV_PROFILE`, `CIRESK_CI_PROFILE`	The keychain profile, below `--profile`, in that order. `CIRESK_DEV_PROFILE` is read by `ciresk dev` only, so one shell can run `ciresk ci` on one key and `ciresk dev` on another.
`CIRESK_AGENT`	The agent the CLI runs for, as `<tool>[/<version>]`. Sent with every API call and shown in the audit next to the person. Without it, Claude Code and Codex are detected from their own environment variables. It never grants anything.
`CIRESK_EGRESS_FILE`	The machine's egress file: the hosts the CLI may reach. Default `~/.ciresk/egress.yaml` (`%USERPROFILE%\.ciresk\egress.yaml` on Windows), which the installer writes. Without a file nothing leaves; a named file that is missing or does not load is refused.
`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`	The proxy the CLI connects through.
`CIRESK_CI_CACHE_DIR`	The cache directory, shared with `ciresk ci`.

Durations are written 500ms, 30s, 2m or 2h; a bare number is seconds.

When the API answers 429 to a read, or to a call that carries an idempotency key, the CLI sends it again up to twice, after the wait the answer names (1 second when it names none), as long as that wait is at most 5 seconds. A longer wait, or a third 429, ends the command with exit 5 and the wait in the message. See rate-limits.md.

Sessions

ciresk dev up

Terminal

ciresk dev up [<template>] [--recreate] [--remote] [--lazy] [--idle <duration>] [--param <name=value>]... [--preset <name>] [--timeout <duration>] [--no-wait]

Starts this worktree's session from a template in .ciresk/dev.yaml, or returns the one already running, and prints its URLs. It waits until the session is ready, showing each service on its way on stderr. See templates.md and sessions.md.

Argument or flag	Type	Default	Meaning
`<template>`	string	the template whose paths hold the current directory, else the one named like the repository	The template in `.ciresk/dev.yaml`.
`--recreate`	switch	off	Stop the running session and start a new one. With `--remote`, start from the trunk instead of the last checkpoint.
`--remote`	switch	off	A session from the repository's trunk with no local tree. Continues this worktree's ended remote session from its last checkpoint when there is one.
`--lazy`	switch	off	Fetch file content on first read instead of before the start.
`--idle <duration>`	duration	the organization's or the template's	This session's idle stop, e.g. `30m` or `2h`, within the organization's bounds (`ciresk dev policy show`).
`--param <NAME=VALUE>`	string, repeatable	none	A template parameter's value, e.g. `--param seed=none`. Split at the first `=`.
`--preset <name>`	string	none	One of the template's presets; its values apply before `--param`.
`--timeout <duration>`	duration	`120s`	How long to wait; counted from the last time a starting service moved.
`--no-wait`	switch	off	Return once the session is created.

ciresk dev down

Terminal

ciresk dev down [--idempotency-key <key>]

Ends this worktree's session.

Flag	Type	Default	Meaning
`--idempotency-key <key>`	string	generated	Makes a retried call act once.

ciresk dev stop

Terminal

ciresk dev stop [--idempotency-key <key>]

Stops this worktree's remote session and keeps it: its workspace files are checkpointed and its compute released. It answers once the session is paused. The template's data volumes are not kept: ciresk dev start runs their seed jobs again, and the answer names them (volumes_not_kept). A local session's files are on your machine, so it is refused with not_cloud_writer; use ciresk dev down.

Flag	Type	Default	Meaning
`--idempotency-key <key>`	string	generated	Makes a retried call act once.

ciresk dev start

Terminal

ciresk dev start [<template>] [--timeout <duration>] [--no-wait]

Starts this worktree's stopped remote session again from its checkpoint, with the parameters it was created with. It is ciresk dev up --remote for a stopped session. To have it started for you at a set time, see ciresk dev schedule set.

Argument or flag	Type	Default	Meaning
`<template>`	string	as for `up`	The template in `.ciresk/dev.yaml`.
`--timeout <duration>`	duration	`120s`	How long to wait.
`--no-wait`	switch	off	Return once the session is started.

ciresk dev schedule show

Terminal

ciresk dev schedule show [--template <name> | --all]

Shows this worktree's session's autostart schedule, with its next start and what its last run did.

Flag	Type	Default	Meaning
`--template <NAME>`	string	this worktree's session	The schedule of this template name instead. Cannot be combined with `--all`.
`--all`	switch	off	Every schedule of yours.

ciresk dev schedule set

Terminal

ciresk dev schedule set <HH:MM> [--days <days>] [--tz <zone>] [--template <name>] [--idempotency-key <key>]

Has this worktree's stopped remote session ready at a local time on chosen days. Ciresk dev starts it 5 minutes before HH:MM from its checkpoint, exactly as ciresk dev start does, so the start counts against your budget and session limits. A refused start is recorded in the schedule's last run, and the next chosen day is tried again. A session that is not stopped at that time is left as it is, and a start more than 15 minutes late is skipped. Setting a schedule again replaces it. Only a remote session can be scheduled: a local one answers not_cloud_writer.

Argument or flag	Type	Default	Meaning
`<HH:MM>`	string	required	The local time the session is ready by.
`--days <DAYS>`	string	`weekdays`	A list such as `mon,wed,fri` (`mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`), `weekdays` or `every-day`.
`--tz <IANA>`	string	the `TZ` environment variable	An IANA time zone, e.g. `Europe/Copenhagen`. With neither `--tz` nor `TZ` the command refuses with `usage`.
`--template <NAME>`	string	this worktree's session	Schedule every stopped session of yours with this template name instead.
`--idempotency-key <key>`	string	generated	Makes a retried call act once.

ciresk dev schedule clear

Terminal

ciresk dev schedule clear [--template <name>] [--idempotency-key <key>]

Removes this worktree's session's schedule, or a template's. The sessions stay as they are.

Flag	Type	Default	Meaning
`--template <NAME>`	string	this worktree's session	The schedule of this template name instead.
`--idempotency-key <key>`	string	generated	Makes a retried call act once.

ciresk dev status

Terminal

ciresk dev status [--wait] [--all]

Shows the session: its services, the generation each serves, health, diagnostic counts and the clients attached, with the next command for anything not healthy.

Flag	Type	Default	Meaning
`--wait`	switch	off	Wait, up to 55 seconds, until the session is ready.
`--all`	switch	off	List every live session of yours instead: id, label, state and URL.

ciresk dev wait

Terminal

ciresk dev wait --gen <n> [--timeout <duration>] [--page <path>]

Waits until every running workspace service serves generation n. When that generation failed to build, it fails with diagnostics (exit 1) and the errors; past the timeout it exits 7 with the command to run again.

Flag	Type	Default	Meaning
`--gen <N>`	integer	required	The generation to wait for.
`--timeout <duration>`	duration	`55s`	How long to wait; at most 55 seconds.
`--page <PATH>`	string	none	Open this path in the session's browser first, so its Next.js runtime errors are in the answer.

ciresk dev sync

Terminal

ciresk dev sync [--wait] [--timeout <duration>]

Says whether the session has your local tree.

Flag	Type	Default	Meaning
`--wait`	switch	off	Wait until it has.
`--timeout <duration>`	duration	`30s`	How long to wait; at most 55 seconds.

Connect and editors

ciresk dev open

Terminal

ciresk dev open [--print]

Opens the session's web URL in your browser. A session with no HTTP port answers unknown_service.

Flag	Type	Default	Meaning
`--print`	switch	off	Print the URL instead of opening it.

ciresk dev ssh

Terminal

ciresk dev ssh [<label>] [--read-only] [-- <command>...]

Opens a shell in the session over SSH, with your system's ssh through the per-machine daemon's tunnel. See editors.md.

Argument or flag	Type	Default	Meaning
`<label>`	string	this worktree's session	The session's label.
`--read-only`	switch	off	The read-only shell: its own container, the workspace mounted read-only, a terminal and file reads.
`-- <command>...`	strings	the login shell	A command to run instead of the login shell.

ciresk dev ssh-config

Terminal

ciresk dev ssh-config [--remove] [--dry-run]

Writes one managed block at the end of ~/.ssh/config with two hosts for every live session, <label>.dev.ciresk and <label>-ro.dev.ciresk (read-only), so any SSH-capable editor lists them. The block's ProxyCommand runs the CLI by its absolute path, with the --region, --org and --profile the block was written under where they are not the defaults.

Flag	Type	Default	Meaning
`--remove`	switch	off	Take the managed block out of `~/.ssh/config`.
`--dry-run`	switch	off	Show the change without writing it.

ciresk dev code

Terminal

ciresk dev code [<path>] [--editor <editor>]
ciresk dev code [<path>] --jetbrains [--ide <ide>]

Writes the managed SSH block, then opens an editor over Remote-SSH on the session's read-write host, at the directory you name. On a large monorepo, open the part you work in rather than the root. With --jetbrains it opens JetBrains Gateway with a jetbrains-gateway://connect#... link instead, and prints the link when Gateway does not open. A view member has no editor; ciresk dev ssh --read-only is their terminal.

Argument or flag	Type	Default	Meaning
`<path>`	string	the current directory	The directory to open, relative to where you are.
`--editor <editor>`	enum	`code`	`code` (VS Code), `cursor` or `windsurf`. Cannot be combined with `--jetbrains`.
`--jetbrains`	switch	off	Open JetBrains Gateway on the session's SSH host.
`--ide <ide>`	enum	`idea`	The JetBrains IDE Gateway installs in the session: `idea`, `goland`, `pycharm`, `webstorm`, `rider`, `clion` or `rustrover`. Needs `--jetbrains`.

Run, files and search

ciresk dev exec

Terminal

ciresk dev exec [--container <name>] [--cwd <path>] [--timeout <duration>] [--stdin] [--idempotency-key <key>] -- <argv>...
ciresk dev exec --wait <exec_id>
ciresk dev exec --cancel <exec_id|last>

Runs a command in a session container, e.g. ciresk dev exec -- pnpm vitest run. Output streams back as it comes. On a terminal the CLI exits with the command's own exit code: 124 when the timeout killed it, 128 plus the signal number when a signal ended it. With --json, a command that exits non-zero is exit 1 with its output in the error. Exactly one of <argv>, --wait and --cancel is required.

Argument or flag	Type	Default	Meaning
`-- <argv>...`	strings		The command, after `--`.
`--container <name>`	string	`shell`	A container of the session; the on-demand `shell` container by default.
`--cwd <PATH>`	string	the current directory	The directory inside the worktree to run in.
`--timeout <duration>`	duration	`10m`	Between `1s` and `60m`. At the deadline the command and everything it started is killed (exit 124).
`--stdin`	switch	off	Send this process's stdin to the command.
`--idempotency-key <key>`	string	generated	Makes a retried call act once.
`--wait <EXEC_ID>`	string	none	The result of an exec the daemon holds (one an agent started with `dev_session_exec`), waiting up to 55 seconds. Cannot be combined with `<argv>` or `--cancel`.
`--cancel <EXEC_ID or last>`	string	none	End a running exec of this session, whoever started it. `last` is the last one started from this machine, else the newest the session runs. Cannot be combined with `<argv>`.

ciresk dev logs

Terminal

ciresk dev logs <service> [--tail <n>] [--follow]

Prints a service's last log lines. Without --follow it prints at most the last 200 lines and marks the answer truncated when there were more.

Argument or flag	Type	Default	Meaning
`<service>`	string	required	The service, as `ciresk dev status` names it.
`--tail <n>`	integer	`200`	How many lines to start from.
`--follow`	switch	off	Keep printing new lines until interrupted.

ciresk dev restart

Terminal

ciresk dev restart <service> [--idempotency-key <key>]

Restarts one service and waits up to 55 seconds for it to come back.

Argument or flag	Type	Default	Meaning
`<service>`	string	required	The service to restart.
`--idempotency-key <key>`	string	generated	Makes a retried call act once.

ciresk dev diagnostics

Terminal

ciresk dev diagnostics [--service <name>]

Returns the services' current compile and type errors as data. Paths your path view hides are left out.

Flag	Type	Default	Meaning
`--service <name>`	string	every service	Only this service's diagnostics.

ciresk dev reset

Terminal

ciresk dev reset [--volume <volume>]... [--rebuild] [--idempotency-key <key>]

Puts the session's data back to its seed, in about a second. A template without data answers no_data.

Flag	Type	Default	Meaning
`--volume <VOLUME>`	string, repeatable	every volume	Only these volumes of the template's data.
`--rebuild`	switch	off	Empty the volumes and run the seed jobs again instead of restoring the snapshot.
`--idempotency-key <key>`	string	generated	Makes a retried call act once.

Terminal

ciresk dev login <identity> --cookies [--idempotency-key <key>]
ciresk dev login <identity> --revoke [--idempotency-key <key>]

Logs one of the template's test identities in to the session's app and answers its session cookies for <label>.localhost, or ends that login. Exactly one of --cookies and --revoke is required. A login in the session's browser belongs to the MCP client that holds the browser: call ciresk_login in ciresk dev mcp browser.

Argument or flag	Type	Default	Meaning
`<identity>`	string	required	A test identity the template declares.
`--cookies`	switch	off	Answer the session cookies. Cannot be combined with `--revoke`.
`--revoke`	switch	off	End the identity's login in the session.
`--idempotency-key <key>`	string	generated	Makes a retried call act once.

ciresk dev evidence

Terminal

ciresk dev evidence [--url <path>] [--full-page] [--name <name>] [--out <dir>]

Captures a screenshot, the console and the failed requests of one page as a bundle, redacted in the session, and prints where it saved it. Your organization's download policy must allow it.

Flag	Type	Default	Meaning
`--url <PATH>`	string	`/`	The page to capture, a path of the session's web URL.
`--full-page`	switch	off	Capture the whole page, not only the viewport.
`--name <name>`	string	the time	The bundle's directory name.
`--out <DIR>`	path	the daemon's cache	Write the bundle here instead; it is kept after the session ends.

ciresk dev search

Terminal

ciresk dev search <query> [--regex] [--case] [--path <path>]... [--max <n>]

Searches the session's copy of the workspace. Paths your path view hides are never included.

Argument or flag	Type	Default	Meaning
`<query>`	string	required	What to search for.
`--regex`	switch	off	The query is a regular expression.
`--case`	switch	off	Match letter case.
`--path <PATH>`	string, repeatable	the whole workspace	Only under these workspace paths.
`--max <n>`	integer	`50`	At most this many results, 1 to 500.

ciresk dev checkpoint

Terminal

ciresk dev checkpoint [--idempotency-key <key>]

Takes a remote session's workspace as a tree root now and prints it, with the ciresk ci check --tree <root> command that checks exactly that tree.

Flag	Type	Default	Meaning
`--idempotency-key <key>`	string	generated	Makes a retried call act once.

ciresk dev push

Terminal

ciresk dev push [--base <branch>] [--pr] [--title <text>] [--idempotency-key <key>]

Commits a remote session's workspace as one commit on refs/heads/ciresk/<session> of this worktree's remote, fast-forward only, and with --pr opens the session's pull request or finds the one already open. No flag names another branch, remote or tag, and nothing is force-pushed. It pushes with your organization's secret of purpose git for the forge's host (see ciresk dev secrets set); without one it answers push_credential_missing, and a secret of purpose proxy for that host answers push_credential_proxied. A push is refused before anything is pushed when the change touches .github/workflows/ or a workflow would run on a push to the session branch (push_unsafe_workflows), when the change holds a .git path (push_unsafe_path), and with --pr on a forge that opens no pull requests (change_requests_unsupported). See git.md.

Flag	Type	Default	Meaning
`--base <BRANCH>`	string	this worktree's checked-out branch	The branch the pull request targets.
`--pr`	switch	off	Open the session's pull request into `--base` too, or find the one already open.
`--title <text>`	string	`ciresk: <label>`	The commit message's first line and the pull request's title.
`--idempotency-key <key>`	string	generated	Makes a retried call act once.

Terminal

ciresk dev share <member> --role <role>
ciresk dev share --revoke <member_id>
ciresk dev share --list

Gives a member of your organization view or use of this worktree's session, revokes them, or lists the members. Only the session's owner shares, and only a person. Exactly one of <member>, --revoke and --list is required.

Argument or flag	Type	Default	Meaning
`<member>`	string	none	A member of the organization: a principal subject or an e-mail address. Needs `--role`.
`--role <role>`	enum	none	`view`: status, logs, events, search and the read-only shell. `use`: everything but sharing, including exec, reset, login, the browser and the read-write shell.
`--revoke <MEMBER_ID>`	string	none	Revoke a member and every device grant under it.
`--list`	switch	off	The session's members.

ciresk dev watch

Terminal

ciresk dev watch [--since <seq>] [--follow] [--session <session_id>]

Shows what happens in the session, read-only: execs, applies, restarts, logins.

Flag	Type	Default	Meaning
`--since <seq>`	integer	`0`	Events after this sequence number.
`--follow`	switch	off	Keep following until interrupted, one line per event.
`--session <SESSION_ID>`	string	this worktree's session	A session shared with you (run `ciresk dev attach` first).

ciresk dev attach

Terminal

ciresk dev attach <session_id> [--revoke <grant_id>]

Grants this device a session another device created, such as one shared with you: the device gets the session's tunnel and ports, never its sync.

Argument or flag	Type	Default	Meaning
`<session_id>`	string	required	The session.
`--revoke <GRANT_ID>`	string	none	Revoke this device grant instead.

Templates

ciresk dev init

Terminal

ciresk dev init [--from <file>] [--name <name>] [--app <dir>]... [--write [--force]]

Translates a compose file or a devcontainer into a template and prints it, with what it could not translate and the next step for each. See templates.md.

Flag	Type	Default	Meaning
`--from <FILE>`	path	the first that exists: with `--name`, `infra/<name>/local/compose.yaml` and `infra/<name>/docker-compose.yml`; then `.devcontainer/devcontainer.json`, `compose.yaml`, `docker-compose.yml`	A compose file or a `devcontainer.json` inside the repository.
`--name <name>`	string	`<name>` of an `infra/<name>/...` source, else the repository's folder	The template's name: a lower-case letter, then up to 30 lower-case letters, digits or `-`.
`--app <DIR>`	string, repeatable	none	An app of the monorepo the template installs and serves on its own.
`--write`	switch	off	Merge the template into `.ciresk/dev.yaml`.
`--force`	switch	off	With `--write`, replace a template of the same name.

ciresk dev templates publish

Terminal

ciresk dev templates publish [<template>]

Publishes a template of this worktree's .ciresk/dev.yaml as a version of the organization. Needs dev:templates.write.

Argument	Type	Default	Meaning
`<template>`	string	the one `ciresk dev up` would start here	The template to publish.

ciresk dev templates promote

Terminal

ciresk dev templates promote <version_id> --repo <url>
ciresk dev templates promote <version_id> --all

Makes a version the active one of its template for one repository, or for every repository without a promotion of its own. Needs dev:templates.write, and only a person can promote. Exactly one of --repo and --all is required.

Argument or flag	Type	Default	Meaning
`<version_id>`	string	required	The version, as `ciresk dev templates list` shows it.
`--repo <URL>`	string	none	One repository, as a remote URL or `host/owner/name`.
`--all`	switch	off	Every repository without a promotion of its own.

ciresk dev templates list

Terminal

ciresk dev templates list [--template <name>]

Lists the organization's versions, newest first, and where each is active. Under each version it prints what ciresk dev up takes for it: each parameter as --param <name>=<default> with its type, choices or range and whether it is fixed at create, and each preset as --preset <name> with the values it sets.

Flag	Type	Default	Meaning
`--template <name>`	string	every template	Only this template's versions.

Secrets and dotfiles

ciresk dev secrets list

Terminal

ciresk dev secrets list

Lists every secret's name, purpose, header, hosts and the sessions it selects; never a value. See secrets.md.

ciresk dev secrets set

Terminal

ciresk dev secrets set <name> --host <host>... --repo <*|remote>... [--header <name>] [--template <name>]... [--agent-sessions] [--purpose <proxy|git>] [--keep-value] < value.txt

Creates or replaces an organization secret. The value is read from stdin only, never from an argument or an environment variable, and no command shows it again. A session never holds it: the session gets the variable CIRESK_SECRET_<NAME> (the name upper-cased, - as _), a placeholder valid for that session only, and the value replaces it in the secret's header on a TLS connection to one of its hosts. For example, in .npmrc: //registry.acme.com/:_authToken=${CIRESK_SECRET_NPM_TOKEN}.

--repo, --template and --agent-sessions choose which sessions get the secret; they are not a boundary, since every member who may start a session can use it. Bind only hosts that do not echo request headers back, and read-only tokens. --purpose git makes the secret the credential ciresk dev push pushes with instead: a token for an HTTPS forge, or an OpenSSH private key for an SSH one, bound to the forge's host by --host; no session gets a placeholder for it.

Argument or flag	Type	Default	Meaning
`<name>`	string	required	Lower-case letters, digits, `-` and `_`, at most 63.
`--host <HOST>`	string, repeatable	required	A host the value is attached for, exact: `registry.acme.com` or `registry.acme.com:8443`.
`--repo <REMOTE>`	string, repeatable	required	`*` for every repository, or one as a remote URL or `host/owner/name`.
`--header <NAME>`	string	`authorization`	The request header the value goes in, e.g. `x-api-key` or `private-token`.
`--template <NAME>`	string, repeatable	any template	Only sessions of this template.
`--agent-sessions`	switch	off	Sessions an agent, a service or a key started get it too.
`--purpose <purpose>`	enum	`proxy`	`proxy` attaches the value to a session's requests to its hosts; `git` is the push credential for them.
`--keep-value`	switch	off	Send no value and keep the stored one. Only for a pure narrowing (fewer repositories or templates, agent sessions off); anything else needs the value again (`value_required`).

ciresk dev secrets rm

Terminal

ciresk dev secrets rm <name>

Deletes a secret and its value. Sessions lose it within 5 minutes.

Argument	Type	Default	Meaning
`<name>`	string	required	The secret.

ciresk dev dotfiles show

Terminal

ciresk dev dotfiles show

Shows your dotfiles repository, its install script, and whether a new session of yours would apply it now.

ciresk dev dotfiles set

Terminal

ciresk dev dotfiles set <url> [--install <path>]
ciresk dev dotfiles set --repo <url> [--install <path>] --token-stdin < token.txt

Sets your dotfiles repository. Sessions you start afterwards clone it in the read-write shell when that shell first starts, then run --install, else install.sh, else bootstrap.sh, else link every top-level dot-file into your home. The clone goes through the session's egress, so your organization's policy and egress decide whether it is let out. The URL is https://, never ssh:// or git@. A running session keeps the shell it started with; ciresk dev up --recreate applies the change.

For a private repository, add --token-stdin and pipe in a read-only token scoped to that repository. The token is read from stdin only, never from an argument, before anything is sent, and no command shows it again. It is kept in the installation's secret store and attached by the session's egress proxy for the repository's host only. The session holds a placeholder, never the token, but any process of yours in the session can use it against that host. Only a person can store a token; an agent cannot.

Argument or flag	Type	Default	Meaning
`<URL>`	string	required unless `--repo` is given	The repository: `https://<host>/<path>`. Cannot be combined with `--repo`.
`--repo <URL>`	string	none	The repository, in place of the positional URL.
`--install <PATH>`	string	`install.sh`, then `bootstrap.sh`, then linking	The script to run, a path inside the repository.
`--token-stdin`	switch	off	Read a token for the repository's host from stdin: 16 to 8192 bytes, one trailing newline dropped. Stdin must not be a terminal; a refused token is `dotfiles_invalid`.

ciresk dev dotfiles rm

Terminal

ciresk dev dotfiles rm

Removes your dotfiles repository; sessions you start afterwards get the plain shell.

Policy, usage and admin

ciresk dev policy show

Terminal

ciresk dev policy [show]

Shows the policy and the path view that apply to you: the organization's policy, its limits and budget, and whether your path view hides or narrows any path. With --json, data is {policy, view}. See admin.md.

ciresk dev policy set

Terminal

ciresk dev policy set <file>

Writes a new policy version from a JSON file holding the whole policy. Its version must be the current one plus one, else policy_version_conflict; a document that does not hold together is policy_invalid. Needs dev:policy.write, and only a person can set it.

Argument	Type	Default	Meaning
`<file>`	path	required	The policy document.

ciresk dev policy preset

Terminal

ciresk dev policy preset <name>

Writes a new policy version from a preset over the current policy; everything the preset does not name stays as it is. Needs dev:policy.write, and only a person can set it.

Argument	Type	Default	Meaning
`<name>`	enum	required	`no-local-checkout`: local sync, downloads and the clipboard off, and a 24 hour session lifetime unless one is already set.

ciresk dev usage

Terminal

ciresk dev usage

Shows what your sessions used today and the organization's this month, in Ciresk CI's cost unit, against the budget: used, reserved ahead of live sessions, what is left and when each window resets. See budgets.md.

ciresk dev kill

Terminal

ciresk dev kill <session_id> [--reason <text>] [--yes]
ciresk dev kill --owner <subject> [--reason <text>] [--yes]
ciresk dev kill --all [--reason <text>] [--yes]

The kill switch: stops a session, every live session of one owner, or every live session of the organization, now. It asks for confirmation on a terminal; without a terminal it is refused unless --yes is given, and declining exits 6. Needs dev:sessions.kill; an agent can never use it. Exactly one of <session_id>, --owner and --all is required.

Argument or flag	Type	Default	Meaning
`<session_id>`	string	none	The session to kill.
`--owner <SUBJECT>`	string	none	Every live session of this principal subject, e.g. `user:<id>`.
`--all`	switch	off	Every live session of the organization.
`--reason <TEXT>`	string	none	Recorded in the session's event log and the audit log; at most 200 characters.
`-y`, `--yes`	switch	off	Kill without asking.
`--idempotency-key <key>`	string	generated	Makes a retried call act once.

ciresk dev connections

Terminal

ciresk dev connections [--session <session_id>] [--principal <subject>] [--since <time>] [--until <time>] [--limit <n>] [--cursor <cursor>]

The connection log, oldest first: who reached which session, from which device, by which stream, with how many bytes, in windows of about a minute. Covers the whole organization and needs dev:audit.read.

Flag	Type	Default	Meaning
`--session <SESSION_ID>`	string	every session	Only this session's windows.
`--principal <SUBJECT>`	string	everyone	Only this person's or agent's windows: `user:<id>` or `agent:<id>`.
`--since <TIME>`	RFC 3339 time	none	Windows that end at or after this moment.
`--until <TIME>`	RFC 3339 time	none	Windows that start before this moment.
`--limit <n>`	integer	`50`	1 to 200 per page.
`--cursor <cursor>`	string	none	The next page, as the last one named it.

ciresk dev egress

Terminal

ciresk dev egress [--denied | --decision <allowed|denied>] [--since <time>] [--until <time>] [--limit <n>] [--cursor <cursor>]

This worktree's session's egress decisions, oldest first: what left it, what was refused, and the policy change that would let a refused request out. See egress.md.

Flag	Type	Default	Meaning
`--denied`	switch	off	Only the refused requests; the same as `--decision denied`.
`--decision <decision>`	enum	both	`allowed` or `denied`. Cannot be combined with `--denied`.
`--since <TIME>`	RFC 3339 time	none	Windows that end at or after this moment.
`--until <TIME>`	RFC 3339 time	none	Windows that start before this moment.
`--limit <n>`	integer	`50`	1 to 200 per page.
`--cursor <cursor>`	string	none	The next page, as the last one named it.

ciresk dev admin enrol-worker

Terminal

ciresk dev admin enrol-worker <name> [--revoke]

For an installation that runs its own worker hosts (see hybrid.md). Issues a worker host's enrolment secret (dve_...), shown once, and prints the line to run on the worker's host. That line writes the secret, pasted at a silent prompt, to /etc/ciresk-ci/dev-enrolment, the file the host's worker.toml names under [dev] as enrolment_secret = "file:/etc/ciresk-ci/dev-enrolment". The name's previous secret stops working. The worker reuses it to register again whenever its token lapsed, until it is rotated or revoked. Needs dev:workers.admin.

Argument or flag	Type	Default	Meaning
`<name>`	string	required	The worker's name.
`--revoke`	switch	off	Cut the worker off instead: its enrolment secret and worker token stop working at once.

ciresk dev admin drain-worker

Terminal

ciresk dev admin drain-worker <name> [--undrain]

Drains a worker host for a roll: it gets no new session while the sessions it holds run on, and it stays drained across its own restart until undrained. Needs dev:workers.admin.

Argument or flag	Type	Default	Meaning
`<name>`	string	required	The worker's name, e.g. its instance id.
`--undrain`	switch	off	Give the worker sessions again.

Agents and MCP

ciresk dev mcp

Terminal

ciresk dev mcp

Runs the stdio MCP server with the dev_session_* tools, acting on the session of the worktree the client runs in. Register it in your agent's MCP configuration as the server ciresk-dev, with the command ciresk and the arguments dev mcp; ciresk dev setup --agents prints or writes the registration for you. See mcp.md.

ciresk dev mcp browser

Terminal

ciresk dev mcp browser

MCP over stdio to the session's browser (a Playwright MCP server), through the per-machine daemon. Its tools act on the session's pages only, and include ciresk_login and ciresk_evidence.

ciresk dev mcp next

Terminal

ciresk dev mcp next [--service <name>]

MCP over stdio to a service's Next.js dev MCP endpoint (its errors, routes and logs). A service that declares none answers no_next_mcp.

Flag	Type	Default	Meaning
`--service <name>`	string	`web`	The service that declares `next_mcp`.

ciresk dev needs

Terminal

ciresk dev needs [list] [--all] [--session <session_id>]
ciresk dev needs --number <n> [--wait <duration>] [--session <session_id>]

Lists the session's open needs: what an agent is blocked on from its person. With --number it reads one need whatever its state, which is how an agent reads the answer.

Flag	Type	Default	Meaning
`--all`	switch	off	Answered and dismissed needs too.
`--number <N>`	integer	none	One need. Put it before `list`, or leave `list` out.
`--wait <duration>`	duration	none	With `--number`, wait up to this long, at most 55 seconds, for the person to answer.
`--session <SESSION_ID>`	string	this worktree's session	A session shared with you (run `ciresk dev attach` first). Works with every `needs` subcommand.

ciresk dev needs raise

Terminal

ciresk dev needs raise --kind <kind> <text> [--link <link>]

Tells your person you are blocked on them, e.g. ciresk dev needs raise --kind approval "may I drop users_old?". The answer names the --number to wait on.

Argument or flag	Type	Default	Meaning
`--kind <kind>`	enum	required	`question` (the agent cannot go on without an answer), `approval` (it wants a yes before it acts) or `failing-check` (a check fails and it cannot fix it).
`<text>`	string	required	One line the person reads at a glance, at most 280 characters.
`--link <link>`	string	none	One URL or reference: `exec:<id>`, `evidence:<path>`, a CI job URL.

ciresk dev needs reply

Terminal

ciresk dev needs reply <number> <reply>

Answers a need; the agent reads the reply. Only a person can reply.

Argument	Type	Default	Meaning
`<number>`	integer	required	The need.
`<reply>`	string	required	The answer.

ciresk dev needs dismiss

Terminal

ciresk dev needs dismiss <number>

Closes a need unanswered.

Argument	Type	Default	Meaning
`<number>`	integer	required	The need.

Setup and diagnostics

ciresk dev doctor

Terminal

ciresk dev doctor

Checks this machine, one line per check with the fix when one fails: whether *.localhost resolves to loopback, core.autocrlf in this worktree, the .localhost resolver, where the device key is kept, whether any service of the session is at its file watch limit, and the policy that applies to you (shown, never a failure). It exits 1 when a check fails. See troubleshooting.md.

ciresk dev setup

Terminal

ciresk dev setup --resolver
ciresk dev setup --agents [--repo] [--remove]

--resolver points .localhost at the per-machine daemon's resolver, once, in an elevated shell (on Windows, a PowerShell started with Run as administrator); without elevation it answers elevation_required. --agents installs the Claude Code and Codex hooks, the ciresk-dev agent skill and the MCP servers. One of --resolver and --agents is required. Running it again replaces what an earlier run added.

The MCP servers are ciresk-dev (ciresk dev mcp) and ciresk-dev-browser (ciresk dev mcp browser), and with --repo also ciresk-dev-next (ciresk dev mcp next --service <name>) when a service of the repository's .ciresk/dev.yaml declares next_mcp. Without --repo your clients keep their servers in files of their own, so the command writes none of them and prints the registration for each instead:

Claude Code: one claude mcp add --scope user <server> -- ciresk dev mcp ... command per server (claude mcp remove --scope user <server> with --remove).
Codex: the [mcp_servers.<server>] tables to add to ~/.codex/config.toml.
Cursor: the mcpServers object to add to ~/.cursor/mcp.json.

With --repo it writes the servers into the repository's .mcp.json for Claude Code and prints the tables for .codex/config.toml and the object for .cursor/mcp.json. Codex asks once to trust new hooks: open /hooks in Codex and accept them.

Flag	Type	Default	Meaning
`--resolver`	switch	off	Set up the `.localhost` resolver.
`--agents`	switch	off	Set up the agent integration. Cannot be combined with `--resolver`.
`--repo`	switch	off	With `--agents`: into this repository (its `.claude`, `.codex`, `.agents` and `.mcp.json`) instead of your home directory.
`--remove`	switch	off	With `--agents`: take the integration out again.

CI records

ciresk dev ci

Terminal

ciresk dev ci [list] [--session <session_id>]

Lists the session's CI records, newest first: the Ciresk CI jobs that ran on the session's tree, as verified with Ciresk CI. See ../ci/quickstart.md.

Flag	Type	Default	Meaning
`--session <SESSION_ID>`	string	this worktree's session	A session shared with you (run `ciresk dev attach` first). Works with `ci record` too.

ciresk dev ci record

Terminal

ciresk dev ci record <job_id>

Attaches a finished CI job on the session's tree, e.g. ciresk dev ci record job_0190.... A job still running answers ci_job_running; a job on another tree tree_not_in_session.

Argument	Type	Default	Meaning
`<job_id>`	string	required	The job id `ciresk ci check --json` printed as `data.id`.

Exit codes

Code	Meaning	Examples
`0`	Success.
`1`	The operation failed.	`no_session`, `session_failed`, `service_not_ready`, `session_not_running`, `stale_epoch`, `need_not_open`, `exec_failed`, `push_credential_missing`, `non_fast_forward`, `policy_version_conflict`; `doctor` with a failed check
`2`	Usage: the command line, a file or a value is wrong.	`usage`, `no_template`, `template_invalid`, `parameter_invalid`, `validation_failed`, `secret_invalid`, `value_required`, `dotfiles_invalid`
`3`	Not signed in, the credential is not valid, or the organization is in another region.	`unauthenticated`, `wrong_region`
`4`	Refused by a scope, a role or your organization's policy.	`insufficient_scope`, `not_allowed`, `writer_conflict`, `access_changed`, `person_session_limit`, `org_session_limit`, `idle_out_of_bounds`, `session_too_large`, `egress_denied`, `template_not_published`, `sharing_ceiling`, `delegated_session`, `branch_fixed`, `org_erasing`, `too_many_ci_records`, `elevation_required`
`5`	Budget, plan or rate limit.	`budget_exceeded`, `rate_limited`, `client_stream_limit`, `product_not_licensed`, `licence_expired`, `licence_not_yet_valid`, `licence_ceiling_reached`
`6`	Cancelled.	`cancelled`, a `kill` not confirmed
`7`	Timed out.	`not_ready`, `not_in_sync`, `not_serving`, `exec_timed_out`; `wait` past its timeout
`8`	Infrastructure: the service, the tunnel or the daemon is unavailable.	`unavailable`, `tunnel_unavailable`, `daemon_unavailable`, `no_capacity`, `no_worker`, `secrets_unavailable`, `internal`

An error code the CLI does not know takes its exit code from the HTTP status: 401 is 3, 403 is 4, 429 is 5, 5xx is 8, anything else 2. A 429 that names its wait says it in the message and in next ("wait N s, then run the same command again").

ciresk dev exec on a terminal is the exception: it exits with the command's own code, 124 when its timeout killed it, and 128 plus the signal number when a signal ended it.