CLI reference

Drive Marshal from your terminal. With marshal you open a space and work in it from your own shell, script headless agent runs, connect VS Code or Cursor to a space over SSH, and reach a dev server in a space as if it ran on your laptop. This page lists every command and flag. Run marshal <command> --help for the same information in your terminal.

Run and deputy commands are available when your administrator enables runs and deputies.

Quickstart

Install the CLI, log in, and open your first space:

curl -fsSL https://marshal.codes/downloads/install.sh | sh
marshal login --server https://<your-marshal-host>
marshal spaces new --manifest <manifest-name>

The last command creates a space and drops you into its terminal. Run marshal manifests list to see the manifests you can use. For more on installing, see Install the CLI.

Recipes

Run an agent from a script

marshal run --follow streams the transcript and exits non-zero when the run ends in any status other than succeeded. A script or CI step can use the exit code as a pass or fail. When the run parks to wait for an answer, --follow keeps waiting, then streams the run that picks the work up again. The exit code is the result of that final run.

marshal run --manifest reviewer --task "Review the open changes and write a summary to output.json" --follow

The run uses your saved login. It gets your org’s default time budget, or 15 minutes when the org has none. To set the budget yourself, add --timeout 30m.

To read the result in a script, add --json. The command prints one JSON object on stdout, and everything meant for a person goes to stderr:

marshal run --manifest reviewer --task "Summarize the open changes" \
  --output-mode transcript --follow --json 2>/dev/null | jq '.output'

Open a space in VS Code

Let VS Code Remote-SSH, Cursor or Windsurf reach your spaces:

marshal daemon install
marshal ssh-config install

Then, in VS Code, choose Remote-SSH: Connect to Host and pick <space-slug>.<org-slug>.marshal. The space’s stack needs the allow-list package for your editor, such as egress-vscode.

Reach a dev server in a space

marshal ports auto-forward my-space

The command watches the space and forwards each new port to your machine, so http://localhost:3000 opens the app the agent started. It picks a free local port when the same port is in use. Press Ctrl+C to stop.

Global flags

These flags work on every command.

The CLI saves its settings in ~/.marshal/config.json. The global flags are never written there; use marshal login or marshal config set to change what is saved. A <id> argument for a space accepts the space ID, its name, or an ID prefix. Most commands need a login first and print not logged in if you have none.

Sign in

marshal login

Log in to Marshal. On a machine with a display, this opens your browser. On a machine without one, such as an SSH session or a Linux server, it switches to device login: the CLI prints a link and a code, and you approve the sign-in from any device where you are signed in to Marshal.

--device, --browser and --password cannot be combined.

Plain marshal login picks device login for you when there is no display: an SSH session without a forwarded display, or a Linux machine with neither DISPLAY nor WAYLAND_DISPLAY set. It prints a one-line notice when it does. On macOS and Windows it uses the browser unless you are connected over SSH.

marshal login --server https://app.marshal.codes
marshal login --device
marshal login --browser
marshal login --password

In a script, --password reads the email and the password from stdin, one per line:

printf '%s\n%s\n' "$MARSHAL_EMAIL" "$MARSHAL_PASSWORD" | marshal login --password --server https://app.marshal.codes

With device login, the CLI signs in to the organization that was active on the approval page. See Sign in on a remote server.

marshal register

Create a new Marshal account. Your install decides who can register. See Signing in and access.

marshal register --invite https://app.marshal.codes/accept-invite/<token>

When your install accepts new accounts by invitation only, --invite is how you register from the CLI. Without it, the CLI tells you to ask an admin for an invite link.

marshal logout

Forget the saved login on this machine.

marshal version

Print the versions of the CLI, the local daemon, and the API server. It does not fail when the daemon or the server is unreachable.

marshal upgrade

Update the CLI to the latest compatible version.

Spaces

marshal spaces has the alias marshal space. The commands stop, resume, and fork also exist at the top level with the same behavior.

Flags:

marshal spaces new --manifest claude-code
NAME=$(marshal spaces new --manifest claude-code --detach)
marshal spaces exec my-space -- git status
marshal spaces push my-space ./diagram.png /home/agent/shared/diagram.png

spaces connect, spaces new, spaces fork, spaces resume --connect and deputies engage open an interactive shell, so they run in a terminal. In a script or a CI job, create the space with --detach and work in it with marshal spaces exec. Started without a terminal, these commands stop before they change anything and print the command to use instead.

Ports

marshal ports moves network traffic between your machine and a space. Each command takes the space as its first argument.

marshal ports forward my-space 8080:3000
marshal ports expose my-space 5432:15432   # localhost:5432 at port 15432 in the space

SSH config

marshal ssh-config lets VS Code Remote-SSH, Cursor, Windsurf, and plain ssh reach your spaces. Each space appears as <slug>.<org-slug>.marshal. The local daemon owns the file.

Runs

Runs are headless agent tasks.

marshal run

Start a headless run.

marshal run --manifest my-stack --task "review the repo" --follow

When the run starts, the command prints the run’s time budget, for example timeout 2h. If the budget ends the run, the command says so and names the two ways to give a run more time: --timeout for the next run, and marshal runs timeout --add for a live one.

JSON output

With --json, marshal run, marshal runs continue and marshal runs get print one JSON object on stdout and nothing else. Without --follow, it describes the run as created. With --follow, it describes the final run, which is the last run of a chain when the work parked and resumed. The exit code does not change: it is non-zero unless the run succeeded.

Every field is always present, with null when there is no value. If the run cannot be started, nothing is printed on stdout, the error goes to stderr, and the exit code is non-zero.

marshal runs

marshal runs timeout flags:

A run can never run longer than 24 hours in total, pauses included.

marshal runs continue flags:

marshal runs continue <run-id> --message "Now run the tests and fix what fails" --follow

marshal runs list --json prints one array with an element for each row of the text list. A run has the fields above. A launch that is waiting to start has an id that starts with ql_, its queue state as status, and the fields kind, deputy and reason. Its run-only fields are null.

Deputies

marshal deputies has the alias marshal deputy.

marshal deputies launch flags:

The run uses the deputy’s identity, environment, and manifest, not yours. This is different from marshal run, which starts a run with no deputy.

marshal deputies launch pr-sweeper --mission nightly-triage --input repo=acme/api

When the mission is already running as many times as its limit allows, the launch waits in a queue. The CLI prints the launch ID (it starts with ql_) and its place in the queue. Cancel it with marshal runs cancel ql_<id>. With --follow, the CLI waits for the launch to start and then streams its run.

Manifests, credentials, and connections

Add a credential

marshal credentials add follows the same rules as the Connect dialog on the Connections page. Every credential has a type of the form <package>.<method>, for example github.pat or aws.sso. Run the command with no flags and Marshal lists the installed packages and their methods for you to pick from. Then it asks for exactly what that method needs:

• A pasted value, such as a token or a connection string. Marshal asks for each field of the method and hides secret ones as you type.
• A browser sign-in (OAuth), such as github.oauth. Marshal opens the provider’s approval page in your browser and finishes as soon as you approve.
• A sign-in with a code, such as aws.sso. Marshal shows a short code and opens the sign-in page. After you approve, you pick the account and the role, check who signed in, and save.

With --type, Marshal skips the pickers and asks only for the method’s values. Pass those as flags too and the command runs with no prompts, so it works in scripts:

marshal credentials add --type github.pat --name "GitHub work"   # asks for the token
marshal credentials add --type k8s.kubeconfig --file ~/.kube/config --owner team:platform
marshal credentials add --type aws.sso \
  --field start_url=https://acme.awsapps.com/start --field region=us-east-1 \
  --account 123456789012 --role ReadOnly --yes

Organizations, members, invitations, and API keys

marshal org has the aliases orgs and organization.

Once your install has its first organization, creating more is off unless your operator turns it on (auth.disableOrgCreation: false, see Configuration). While it is off, marshal org create returns org_creation_disabled.

marshal member has the alias members.

To remove a member, use Organization settings > Members in the web app, where you also pick new owners for what they share. See Remove a member or leave an organization.

marshal invite has the aliases invites, invitation, and invitations.

marshal api-key has the aliases api-keys and apikey.

marshal invite create --role=member --email=alice@example.com
marshal api-key create ci-deploy --role=member
marshal api-key create agent --role=admin --mcp-scopes read,launch,answer,manage
marshal member role alice@example.com admin

For what each role can do, see Roles and permissions.

Local daemon

The daemon runs on your machine. It runs the port forwards and mounts you open from the Ports and Mounts tabs of a space in the web app, and it manages the SSH config. The CLI’s own marshal ports forward and --mount run inside the CLI and need no daemon.

Settings and shell completion

Related

• Roles and permissions
• Spaces
• Runs
• Help and fixes