CLI reference

Every agentry command, with examples.

The CLI is a thin client: it talks to your server through the agentry bridge and the real work happens there. A few commands manage local state under ~/.agentry/.

Terminology

A server is the machine that runs your sandboxes. The commands accept both server and the older alias cluster — they're interchangeable.

Synopsis

agentry <command> [args...]

See usage any time with agentry help or agentry help <command>.

Setup

agentry login

Sign in. Opens a browser, completes sign-in, and saves a token under ~/.agentry/. Run once per machine.

agentry login

agentry logout

Revoke the local token and clear it.

agentry logout

agentry init

Enroll this machine as a device against your account. The dashboard's Add this machine panel gives you the full command with the token pre-filled, so you rarely type this by hand.

agentry init --token <token> --name <device-name>

Flag	Description
--token	Single-use enrollment token from the dashboard
--name	Friendly device name (defaults to hostname)
--app-url	Control-plane URL (defaults to https://app.agentry.run)

agentry status

Show local config — current device, server, and pinned sandbox. No network calls; safe when the tunnel is down.

agentry status

agentry version

Print the build version. Also agentry -v, agentry --version.

Servers

agentry server

Interactive picker — lists your servers and sets the current one. (Alias: agentry cluster.)

agentry server

agentry server ls

List your servers and their status.

agentry server ls

agentry server use <name>

Set the current server by name. Everything else targets it until you change it.

agentry server use homelab

agentry server current

Print the current server.

Sandboxes

agentry sandbox ls

List sandboxes on the current server. (Alias: agentry sandbox list.)

agentry sandbox ls

agentry sandbox use <id>

Pin a sandbox as the default for env and service commands.

agentry sandbox use ecommerce-store

agentry sandbox current

Print the pinned sandbox.

agentry sandbox rm <id>

Delete a sandbox and free its resources. (Alias: agentry sandbox delete.)

agentry sandbox rm old-prototype

Download a sandbox

agentry pull [<sandbox>]

Download a sandbox's project to a local folder — handy for committing to your own git repo. Defaults to the pinned sandbox. Build junk (node_modules, .next, dist, .venv, …) is skipped automatically.

agentry pull                              # the pinned sandbox → ./
agentry pull my-app --to /tmp/my-app      # a specific sandbox → a folder
agentry pull my-app --archive backup.tgz  # as a tarball

Flag	Description
--to <dir>	Destination folder
--archive <file.tar.gz>	Write a tarball instead of a folder
--exclude <pattern>	Add an exclude (repeatable)
--no-excludes	Include everything, even build junk
--force	Overwrite a non-empty destination

Work inside a sandbox

Get your own hands on a running sandbox — a shell, live logs, or a full editor. All three default to the current sandbox when you omit <sandbox>, and all need CLI v0.6.4+. Full walkthrough: Work inside a sandbox.

agentry sh [<sandbox>]

Open an interactive shell inside the sandbox, landing in /workspace. Runs over the broker tunnel; needs an interactive terminal. Defaults to the current sandbox.

agentry sh                  # the current sandbox
agentry sh ecommerce-store  # a specific sandbox

agentry logs [<sandbox>] [-f] [-n N]

Show the sandbox's project logs. Snapshot mode prints the last N lines; follow mode streams live. Defaults to the current sandbox.

agentry logs            # last 100 lines
agentry logs -f         # stream live (Ctrl-C to stop)
agentry logs -n 500     # last 500 lines
agentry logs my-app -f  # follow a specific sandbox

Flag	Description
-f, --follow	Stream logs live instead of a one-time snapshot
-n, --lines <N>	Lines to show in snapshot mode (default 100)

agentry vsc [<sandbox>]

Open the in-browser editor (VS Code) for the sandbox in your browser — a full editor with an integrated terminal, scoped to /workspace and served behind your dashboard login. The same thing as the Open editor button on the sandbox detail page. First open takes ~15–20 s; later opens are instant. Defaults to the current sandbox.

agentry vsc               # the current sandbox
agentry vsc landing-page  # a specific sandbox

Environment variables

agentry env set NAME [VALUE]

Set an env var. Omit VALUE for a hidden prompt (keeps secrets out of your shell history). Without --sandbox it's saved as a server default and applied to every new sandbox; with --sandbox it's set on that one sandbox now.

agentry env set DEBUG_MODE true
agentry env set STRIPE_SECRET_KEY                 # hidden prompt
agentry env set MONGODB_URL --sandbox quill "mongodb://localhost:27017"

Flag	Description
--sandbox <id>	Set on this sandbox only (otherwise it's a server default)
--profile <name>	Store under a specific profile

agentry env ls

List env var names (never values). (Alias: agentry env list.)

agentry env ls --sandbox quill

agentry env unset NAME

Remove an env var. (Aliases: rm, delete.)

Services (bindings)

A binding wires a service (database, AI provider, …) into your sandboxes. See How bindings work.

agentry service ls

List bindable services and what you've staged. (Alias: agentry service list.)

agentry service bind <service>

Stage a server-default binding — every new sandbox inherits it. Prompts for the values it needs.

agentry service bind postgres                  # prompts for connection URL
agentry service bind anthropic                 # prompts for API key
agentry service bind smtp                       # email, for auth password-reset
agentry service bind stripe --from-env          # read values from your shell env
agentry service bind redis --sandbox quill      # one-shot: this sandbox only

Flag	Description
--from-env	Read values from your shell environment instead of prompting
--sandbox <id>	Apply to one sandbox now, instead of a server default
--profile <name>	Store under a specific profile

agentry service binds

List the server-default bindings staged on this machine.

agentry service unbind <service>

Drop a server-default binding. Existing sandboxes keep what they have.

Profiles

A profile is a named set of env vars, service binds, and auth config. Its contents are stored per server, so the same profile holds different bindings on different servers. Most people stay on default. Full explanation with examples: Profiles & per-server config.

Command	Does
agentry profile	Show the active profile and server
agentry profile list	List all profiles on this machine
agentry profile use <name>	Switch the active profile
agentry profile create <name>	Create an empty profile
agentry profile show [--profile <name>]	Describe a profile's env + binds
agentry profile copy <src> <dst>	Clone a profile
agentry profile delete <name>	Delete a profile (not default or the active one)

Authentication

Configure user login for the apps you deploy. Full guide: Authentication.

Command	Does
agentry auth enable [--db postgres|mysql|mongo]	Turn on app login (checks the DB, mints a session secret)
agentry auth disable	Turn it off
agentry auth status	Show what's enabled
agentry auth providers add <name> --client-id … --client-secret …	Add a social provider (google, github, microsoft, generic-oidc)
agentry auth providers list	List configured providers
agentry auth providers remove <name>	Remove a provider
agentry auth sync	Re-apply auth settings to running sandboxes

Editor integration

agentry mcp

The MCP server your harness runs over stdin/stdout. Your harness config invokes this — you don't run it by hand. (Alias: agentry stdio for older configs.)

agentry mcp
agentry mcp --server homelab    # pin this session to one server

It holds the tunnel open and dispatches every tool call to the current server. Restart your harness to restart it.

Flag	Description
--server <name>	Pin this MCP session to a specific server, ignoring later agentry server use switches. Lets you run one harness against laptop and another against production at the same time.

Help

agentry help            # usage summary
agentry help <command>  # detail for one command

Also agentry -h, agentry --help.

What the CLI doesn't do

By design, some actions live only in the dashboard:

• Deploying and sharing a sandbox — both are dashboard actions (Ship an app). There is no agentry deploy.
• Managing devices — see Settings → Devices in the dashboard.

Configuration files

Everything lives under ~/.agentry/:

• agentry.json — token, current server, device cert paths.
• state.json — the pinned sandbox.
• envs/, services/, auth/ — per-server, per-profile env, binds, and auth.

You shouldn't edit these by hand; the commands above write them. See Configuration.

Next

• MCP tools — every tool your harness can call.
• Configuration — the files under ~/.agentry/.
• Environment variables — env that changes agentry's behavior.