Offline commands

List, send and drop the writes this machine keeps when it cannot reach the service.

When a write waits on this machine

Sometimes the tool cannot reach the service. The network may be down, a proxy may refuse, or the service may fail. Then the tool keeps most writes on this machine, in a private queue, and sends them later. Such a write is pending: the service has not accepted it yet. Nothing in the record changed.

These writes can wait in the queue: open, save, offer, retract, continue, renew, end, note, block, unblock, close, handle add, handle claim, handle disable and workspace create. The tool never queues a read, or a write that the service refused. If you are not signed in, it queues nothing.

To see a write wait, point the tool at a proxy that does not answer. Here HTTPS_PROXY names a local port where nothing listens. The examples use BILL-43 and BILL-44 from Reading work, and run in the order of this page:

$ HTTPS_PROXY=http://127.0.0.1:9 handsoff note BILL-44 --as build-agent --text "Export paused at invoice 2000"
Pending on this machine, not accepted by the record: 1 queued, 0 refused, 0 conflict, 0 unsent; run handsoff pending.
Queued as pending, not accepted: note on BILL-44 (write 0a112dc1119e). The record could not be reached: The record could not be reached; the environment proxy http://127.0.0.1:9 may be refusing or unable to reach the network.. Nothing has changed in the record. This machine sends it when the record answers, within 24 hours; run handsoff sync to send it now, or handsoff pending to list it.

Two notes for BILL-43 wait too. The tool does not send the second of them, because an older write for the same work still waits:

$ HTTPS_PROXY=http://127.0.0.1:9 handsoff note BILL-43 --as dana --text "Draft note, sent by mistake"
Pending on this machine, not accepted by the record: 1 queued, 0 refused, 0 conflict, 0 unsent; run handsoff pending.
Queued as pending, not accepted: note on BILL-43 (write 8c7a1f4fea39). The record could not be reached: The record could not be reached; the environment proxy http://127.0.0.1:9 may be refusing or unable to reach the network.. Nothing has changed in the record. This machine sends it when the record answers, within 24 hours; run handsoff sync to send it now, or handsoff pending to list it.
$ HTTPS_PROXY=http://127.0.0.1:9 handsoff note BILL-43 --as dana --kind question --text "Who restarts the totals report?"
Pending on this machine, not accepted by the record: 2 queued, 0 refused, 0 conflict, 0 unsent; run handsoff pending.
Queued as pending, not accepted: note on BILL-43 (write 7fe9cd1eb821). The record could not be reached: older writes for this work wait on this machine. Nothing has changed in the record. This machine sends it when the record answers, within 24 hours; run handsoff sync to send it now, or handsoff pending to list it.

A queued write ends with exit code 3. While writes wait, most commands print the Pending on this machine line first.

The tool sends queued writes for you. Each command that reaches the service first sends the oldest queued writes, for up to five seconds. Six commands do not send them: login, logout, workspace use, instructions, checks and pending.

A queued write waits for at most 24 hours by this machine's clock. After that it is unsent: the tool stops sending it by itself, and only handsoff pending resend can send it.

A queued continue is not a catch. You do not hold the work until the service accepts the catch, so do not start on it.

handsoff pending

Lists the writes waiting on this machine, oldest first. Each line shows the entry's id, when the tool queued it, its age, the act and its state.

Usage: handsoff pending [OPTIONS] [COMMAND]

Commands:
  discard  
  resend   
  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

Option	What it does
`discard`	Deletes one queued write without sending it. See below.
`resend`	Sends one queued write now. See below.

$ handsoff pending
Pending on this machine, not accepted by the record: 3 queued, 0 refused, 0 conflict, 0 unsent; run handsoff pending.
0a112dc1119e 2026-10-05T04:14:19Z (age 11s): note on BILL-44: pending
8c7a1f4fea39 2026-10-05T04:14:29Z (age 1s): note on BILL-43: pending
7fe9cd1eb821 2026-10-05T04:14:30Z (age 0s): note on BILL-43: pending

The states are:

pending: the write waits for the tool to send it.
refused: the service refused it, and the line gives the reason. The tool never sends it again by itself.
conflict: the work changed while the write waited, and the line gives the reason. For a save, pending prints your text and the current baton in full. The tool never merges them.
unsent: the write is more than 24 hours old.

When the queue is empty, pending prints No pending writes on this machine.

handsoff pending discard

Deletes one queued write from this machine. The tool never sends it. Use it for a write you no longer want, or to clear a conflict.

Usage: handsoff pending discard [OPTIONS] <ID>

Arguments:
  <ID>  

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

Option	What it does
`<ID>`	The entry's id, as `handsoff pending` shows it. The first few characters are enough when no other entry starts with them.

$ handsoff pending discard 8c7a
Pending on this machine, not accepted by the record: 3 queued, 0 refused, 0 conflict, 0 unsent; run handsoff pending.
Discarded note on BILL-43 (write 8c7a1f4fea39).

The first line counted the queue before the discard.

handsoff pending resend

Sends one queued write now, whatever its state or age. The tool reads the work's current state first and sends the write as new. A save goes on top of the current revision.

Usage: handsoff pending resend [OPTIONS] <ID>

Arguments:
  <ID>  

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

Option	What it does
`<ID>`	The entry's id, or its first few characters.

$ handsoff pending resend 7fe9
Pending on this machine, not accepted by the record: 2 queued, 0 refused, 0 conflict, 0 unsent; run handsoff pending.
Resent note on BILL-43 accepted.

If the service refuses the write, the entry stays, marked refused. If the tool still cannot reach the service, the entry stays and the command ends with exit code 2.

handsoff sync

Sends every queued write that can still go, oldest first, with no five-second limit. Use it after the network comes back.

Usage: handsoff sync [OPTIONS]

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

This command has no options of its own.

$ handsoff sync
Sent from the queue: note on BILL-44 accepted.
Queue replay complete; run handsoff pending for anything not accepted.

sync does not send refused, conflicting or unsent entries. Use pending resend or pending discard for those.