Agents CLI
Use codity agent to launch and manage your organization's agents. Use the installed codity-agent runner to continue a saved session on a machine.
Install and authenticate
Install or update the Codity CLI, then sign in:
codity login
codity agent --help
If your login predates Agents support, sign in again. Agent management uses the organization attached to that login. The target machine also needs Node.js 18 or newer and access to the agent service and selected model provider.
Launch a task here
With your provider key already available as OPENAI_API_KEY:
mkdir -p /tmp/codity-agent-demo
cd /tmp/codity-agent-demo
codity agent launch "Write a short hello message to hello.txt in this folder." --model openai/gpt-5.6-luna --strict
Launch creates an agent, grants read/write access to the working directory, installs the runner and runs the task in your terminal. The standard default denies and organization policies still apply. It prints the agent ID and dashboard link.
The provider key comes from --llm-key-env if supplied, otherwise a matching key stored by codity config set-llm, otherwise the provider's environment variable on the target machine. --llm-key-env submits that variable's value to Codity for encrypted storage. To keep a key solely on the machine, leave that flag unset and avoid a stored CLI key for that provider.
Launch defaults to Ask me (request) for unlisted actions; --strict selects Refuse. An interactive launch still takes one positional task argument. You can pass an empty quoted string to start without a task:
codity agent launch "" --interactive --model openai/gpt-5.6-luna --strict
The one-step launch command does not currently expose team assignment or recovery settings. For those, create the agent in the dashboard or through API configuration creation, then install it.
Launch flags
| Flag | Meaning |
|---|---|
--model provider/name |
Choose a provider and model; omit for the server's default. |
--label NAME |
Fleet name; otherwise derived from the task. |
--dir PATH |
Working folder; defaults to the current folder. |
--llm-key-env VARIABLE |
Read the model API key from the named environment variable and submit it with the configuration. |
--interactive |
Open the terminal UI. |
--strict |
Refuse unlisted actions instead of requesting permission. |
--allow-read PATH |
Add filesystem Read access; repeat for multiple paths. |
--allow-write PATH |
Add filesystem Write access; repeat for multiple paths. |
--allow-bash PATTERN |
Add a shell command pattern; quote globs and repeat as needed. |
--allow-host PATTERN |
Add a fetch URL/host pattern; use a full URL pattern such as https://example.com/**. |
--ack-bash-gateways |
Acknowledge command grants that can execute arbitrary commands. Such commands can access files with the machine's permissions. |
--print |
Create the agent and print an install command without executing it. |
--os linux or --os macos |
Target for a printed command; defaults to this machine. |
--json |
Print the launch response without starting the runner. It contains private bootstrap credentials. |
For another Linux machine:
codity agent launch "Summarize the application logs." --dir /srv/my-app --model openai/gpt-5.6-luna --allow-read '/var/log/my-app/**' --strict --print --os linux
Run the printed command from /srv/my-app on the target within five minutes. Ensure the provider key is available there if you did not submit one. The command is single-use; protect it as a credential.
Inspect runs and send messages
Replace AGENT_ID, RUN_ID and REQUEST_ID below with IDs from your own agent:
codity agent list
codity agent show AGENT_ID
codity agent logs AGENT_ID
codity agent logs AGENT_ID --run RUN_ID --follow
codity agent send AGENT_ID "Summarize your findings so far." --run RUN_ID
logs and send use the latest run when --run is omitted. Messages reach a running agent on its next heartbeat; they do not restart a stopped session. --json produces structured output; following logs with --json produces one event per line.
Decide permission requests
codity agent approvals AGENT_ID
codity agent approvals AGENT_ID --interactive
codity agent approve AGENT_ID REQUEST_ID
codity agent approve AGENT_ID REQUEST_ID --run
codity agent approve AGENT_ID REQUEST_ID --always
codity agent deny AGENT_ID REQUEST_ID
Approval defaults to once. --run allows the resource for the current run; --always adds it to the configuration for future runs. These two flags cannot be combined. approvals --all includes decided and expired requests. Explicit shared denies cannot be overridden. See Permissions and YAML policies.
Install an existing configuration
codity agent install-cmd AGENT_ID
This prints a fresh one-machine command. For a reusable command:
codity agent install-cmd AGENT_ID --reusable --label staging --max-installs 3 --expires-days 7
Each machine creates a separate run. Reusable tokens default to seven days, and install limits are optional. Install commands create fresh runs, not recovered sessions.
Resume with codity-agent
The agent installer also installs codity-agent, usually under ~/.local/bin. It does not require a new codity login to resume: the recovery-enabled session has its own scoped machine credential.
codity-agent --help
codity-agent sessions
codity-agent resume --last
codity-agent resume
codity-agent resume SESSION_ID --prompt "Continue with the next task."
codity-agent sessions --all
codity-agent resume --all
Enable recovery before the session starts, wait for a checkpoint, press Ctrl+C and let shutdown finish, then run resume --last from the original folder. resume --all opens a picker across folders. It does not resume all sessions at once.
| Runner flag | Use |
|---|---|
--last |
Select the latest saved session in this working folder. |
--all |
List or choose sessions across folders. |
--prompt "TEXT" |
Supply a follow-up instruction with the restored conversation. |
--reconcile=completed |
Explicitly mark listed interrupted actions as completed after checking their effects. |
--reconcile=retry |
Explicitly allow retry of listed interrupted actions after reviewing possible side effects. |
--accept-workspace-changes |
Consent to a changed checkout/files after reconciling them yourself. |
Session IDs come from codity-agent sessions and identify runs, not fleet configurations. See Session recovery for crashes, another machine and checkpoint limits. There is currently no codity agent resume subcommand; use codity-agent resume.
Stop permanently
codity agent stop AGENT_ID
This revokes the configuration and signals its live runs to stop. It prevents later installs and recovery. For a resumable pause, use Ctrl+C in a recovery-enabled agent terminal instead.
