chainctl develop command reference

The chainctl develop command opens and manages Chainguard Workspaces sessions. This page lists each chainctl develop command, with its flags, output formats, exit codes, and the roles it needs. For how the commands fit together, refer to Manage sessions.

During the beta, the chainctl checks and chainctl develop commands don’t appear in chainctl --help or in the chainctl reference. You can still run them, and --help on either one shows its full help.

To read the help for the version you have installed, run chainctl develop --help, or add --help to any command on this page. You can shorten chainctl develop to chainctl dev. If chainctl doesn’t recognize a command or flag on this page, update chainctl.

The examples on this page use $ORGANIZATION for the name of your Chainguard organization. If you belong to only one organization, you can omit --parent.

Commands

Flags for every command

Every chainctl develop command accepts the following flags:

Session arguments

Commands that take a SESSION argument accept any of the following:

• The session’s name, such as app/quiet-harbor, or the name with the repository’s GitHub owner in front, such as acme/app/quiet-harbor, as chainctl develop list shows it.
• The session’s short ID, such as 3f9a2c1e.
• A directory or a repository URL, if exactly one of your sessions matches it.

If several of your sessions match, chainctl asks which one you mean, or lists them and fails when it can’t ask. Commands find only your own sessions.

chainctl develop

Opens a session and attaches your terminal to its shell. If one of your sessions already matches the argument, chainctl develop returns to it instead, resuming it first if it’s parked.

chainctl develop [DIR|REPO|SESSION] [flags]

The argument is a directory, a repository URL, or a session. Without one, chainctl develop uses the current directory. Refer to How chainctl develop chooses a session for what each one opens.

The --name, --env, --check, --cache, --keep always, and --keep park flags each open a new session, so you don’t need --new with them, and you can’t combine them with a session name.

In a checkout of a repository named app, this example opens a new session named app/scratch with the default environment:

chainctl develop --env default --name scratch --parent $ORGANIZATION

chainctl develop list

Lists your sessions that haven’t expired, most recently used first, with each session’s branch, state, and when you last used it. Alias: ls.

chainctl develop list [--all] [--expired] [-o json|table|wide]

For example output, refer to List sessions.

chainctl develop rename

Replaces the second part of a session’s name. The repository part stays the same. Alias: mv.

chainctl develop rename SESSION NAME [-o json]

This example renames app/quiet-harbor to app/tests:

chainctl develop rename app/quiet-harbor tests --parent $ORGANIZATION

chainctl develop delete

Destroys a session’s VM and its snapshot, after asking you to confirm. Anything in the session that you didn’t push is lost. For an expired session, the command removes it from chainctl develop list --expired and frees its name. Alias: rm.

chainctl develop delete SESSION [--yes] [-o json]

This example deletes app/scratch without asking:

chainctl develop delete app/scratch --yes --parent $ORGANIZATION

chainctl develop check

Runs the checks in a session’s working tree, in the session’s own environment, and streams each step’s output to your terminal. If the session is parked, chainctl resumes it first. The command uses the same runner as the run-ci command in a session.

chainctl develop check SESSION [--check CHECK] [-o json]

This example runs the test check in app/quiet-harbor:

chainctl develop check app/quiet-harbor --check test --parent $ORGANIZATION

For which checks the command skips, and how its result compares with a pull request’s, refer to Run checks in a session from your laptop.

chainctl develop creds

Shows what a session can reach, or changes it.

chainctl develop creds SESSION [--revoke ENTRY]... [--source SERVICE=SOURCE]... [--forget] [-o json|table]

Without flags, the command lists each service’s source and bindings, what your laptop remembers approving, what serves the session’s laptop credentials right now, and the latest changes to the session’s credentials.

To add access, run chainctl develop SESSION --with ENTRY instead. Refer to Review and revoke a session’s credentials for the entries and sources that each service takes.

This example takes back a session’s access to cgr.dev:

chainctl develop creds app/quiet-harbor --revoke cgr.dev --parent $ORGANIZATION

chainctl develop github

Connects your GitHub account so that the sessions you create act on GitHub as you, through the Chainguard Develop GitHub App. Refer to Let sessions act on GitHub as you.

chainctl develop github login [--port PORT] [-o json]
chainctl develop github logout
chainctl develop github status [-o json|table]

chainctl develop claude

Lets Chainguard hold a Claude login for your sessions, so that Claude Code in them works whether or not you’re attached. One login serves your sessions in every organization, except sessions that use Vertex AI. Refer to Let Chainguard hold your Claude login.

chainctl develop claude login [-o json]
chainctl develop claude status [-o json|table]
chainctl develop claude logout

chainctl develop policy

Shows or changes your organization’s GitHub policy for sessions. Alias: policies.

chainctl develop policy describe [-o json|table]
chainctl develop policy set [--org-github bound|session|off] [--org-github-push-beyond-session=true|false] [--user-github=true|false] [-o json|table]

The describe command, with the aliases desc and get, shows the policy, its revision, and who last changed it. The set command changes only the settings you pass, and needs the owner role. Refer to Set your organization’s GitHub policy for what each setting controls.

This example limits the Chainguard App to each session’s own repository:

chainctl develop policy set --org-github session --parent $ORGANIZATION

chainctl develop init

Signs you in, creates a Chainguard Starter organization or picks one you belong to, and turns on Chainguard Checks and Chainguard Workspaces with a free monthly allowance. Run it in an interactive terminal.

chainctl develop init [--parent ORGANIZATION] [--github-org ACCOUNT] [--name NAME] [--port PORT]

Without --parent, the command creates a Starter organization if you don’t belong to any organization, and uses your organization on the Starter or Team plan if you have exactly one. Otherwise, it fails and asks you to pass --parent. Unlike the other commands, it doesn’t fall back to the default.group value in your chainctl configuration.

For what the command asks as it runs, refer to Sign up with chainctl develop init.

chainctl develop accept-terms

Accepts the Secured Platform Terms and the Master Service and License Agreement (MSLA) for an organization. Chainguard Workspaces refuses to open sessions in an organization until it accepts them. Someone with the owner or limited_owner role runs the command once, and running it again changes nothing.

chainctl develop accept-terms [--parent ORGANIZATION] [--yes]

An organization that already has Workspaces through your Chainguard account team must accept the terms before anyone can open new sessions in it. Running chainctl develop init --parent $ORGANIZATION accepts them, turns on Checks, and keeps the allowance your account team arranged. To accept only the Workspaces terms, run chainctl develop accept-terms instead:

chainctl develop accept-terms --parent $ORGANIZATION

If you accept only the Workspaces terms and your GitHub account isn’t linked to the organization yet, link it as described in Getting started with Guardener, which uses the same Chainguard App.

Output formats

Each command accepts only the following output formats:

A session in JSON output includes its name, such as app/quiet-harbor; its label, the name with the repository’s GitHub owner in front; its id and short_id; its state, repository, branch, head, and directory; how it keeps running after you detach, in idle (auto_hold or keep_running), keep_running_until, held_until, and last_busy; and timestamps such as create_time and expire_time. Fields without a value are left out.

Session states

In JSON output, a session’s state is one of the values in the following table, which also shows what the STATE column of chainctl develop list says for each one, as explained in List sessions. For how a session moves from one state to the next, refer to Session lifecycle.

A detached session that Chainguard keeps running because it’s busy can be attached or idle, and the STATE column shows it as running (busy: …). A session that’s parking keeps its attached or idle state until the park finishes. chainctl develop list shows reaped and deleting sessions only with --expired.

Exit codes

Roles

What you can do with chainctl develop depends on your role in the session’s organization:

The limited_owner role is the one that chainctl develop init gives the person who creates a Starter organization. No one in a Starter organization has the owner role, so no one there can run list --all or policy set. On their own, other roles, such as editor and viewer, can’t open or manage sessions. To run chainctl develop init --parent on an organization you already belong to, you need the owner or limited_owner role in it. An organization owner can grant the sandbox.user role with an invite, as described in Give teammates access.

In a session, your role also limits what your Chainguard identity can do. The limited_owner role doesn’t include mcp.tool.call or sandbox.run.list, so the Chainguard MCP servers and the chainctl checks commands that look up a run don’t work for it. Refer to MCP servers in a session and Your Chainguard identity in a session.

Environment variables and configuration