CLI reference

Every command and option of the handsoff tool, each with its help and a real run.

The pages in this section quote the tool's help exactly as it prints it. Most options print no description of their own, so each page explains them in a table under the help.

The examples come from one test workspace, run at different moments. So the names, numbers, times and lists you see will differ. The tool names you by your sign-in id, a long string of letters and digits. handsoff login prints that id. handsoff whoami prints your name, or unknown when your sign-in page sends none, and then the id in brackets.

handsoff

Run handsoff --help to list the commands:

A relay for agent work

Usage: handsoff [OPTIONS] <COMMAND>

Commands:
  adapter       
  hook          
  session       
  login         
  logout        
  whoami        
  workspace     
  handle        
  open          
  baton         
  save          
  offer         
  continue      
  retract       
  block         
  unblock       
  close         
  show          
  list          
  status        
  renew         
  end           
  note          
  history       
  pending       
  sync          
  instructions  
  checks        
  help          Print this message or the help of the given subcommand(s)

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help
  -V, --version                Print version

The commands, by page:

To print the tool's version:

$ handsoff --version
handsoff 0.1.0

Global options

Each command takes the global options that its help lists. Put them before or after the command's name.

A setting comes from the option first. Without the option, the tool reads an environment variable. Without that, it reads its config file, config.json in the config folder. The config file holds only the service, the workspace and the handle.

Two shells with no session id look like one session to the tool. Give each agent session its own id.

Environment variables

The tool reads these variables. The first seven stand in for an option.

When you set both forms of a proxy variable, the uppercase one wins. The tool adds colour and bold only when it prints to a terminal. Output in a pipe and --json output never carry them.

Exit codes

A command never exits with 0 for an act the service did not accept. Every error prints two lines. The first says what happened and what to do, for you. The second gives the code, the detail and the fix, for the agent or script that ran the command.

The examples below run in the billing workspace, after the steps on Workspace and handle commands. A refusal by a rule:

$ handsoff handle disable dana
The owner's person handle must stay enabled; choose another handle.
not_allowed: owner handle cannot be disabled; fix: choose a member handle
$ echo $?
1

A service the tool cannot reach, here through a proxy that does not answer:

$ HTTPS_PROXY=http://127.0.0.1:9 handsoff list
The record could not be reached; the environment proxy http://127.0.0.1:9 may be refusing or unable to reach the network.
unavailable: the record or local state could not be reached; fix: check proxy settings, NO_PROXY, network access and the session's sandbox; retry
$ echo $?
2

JSON output

With --json, a command prints its result as one JSON object instead of plain text.

$ handsoff handle list --json
{"handles":[{"disabled_at":null,"id":"49","kind":"person","name":"dana","principal":"1","role":"owner"},{"disabled_at":null,"id":"50","kind":"agent","name":"build-agent","principal":"1","role":"member"},{"disabled_at":null,"id":"51","kind":"agent","name":"review-agent","principal":"1","role":"member"},{"disabled_at":"2026-10-05T04:12:46.015962+00:00","id":"52","kind":"person","name":"sam","principal":"1","role":"member"}]}

An error with --json prints its first line as usual, then a JSON object with code, message, detail and fix. Both go to standard output, so a script that reads the JSON must skip the first line:

$ handsoff handle disable dana --json
The owner's person handle must stay enabled; choose another handle.
{"error":{"code":"not_allowed","detail":"owner handle cannot be disabled","fix":"choose a member handle","message":"The owner's person handle must stay enabled; choose another handle."}}

handsoff help

Prints the tool's help, or the help of one command. handsoff help <command> prints the same text as handsoff <command> --help. Commands in a group take the group's name first, such as handsoff help workspace create.

$ handsoff help whoami
Usage: handsoff whoami [OPTIONS]

Options:
      --server <SERVER>        
      --workspace <WORKSPACE>  
      --as <HANDLE>            
      --session <SESSION>      
      --runtime <RUNTIME>      
      --model <MODEL>          
      --leg <LEG>              
      --account <ACCOUNT>      
      --json                   
  -h, --help                   Print help

handsoff help with no command prints the same list as handsoff --help.