CLI Playbook

Set up UnoLock on a CLI-only platform

Use this page when the host has no plugin system, no skill loader, and no MCP config. The agent calls unolock-agent directly. The same flow works on macOS, Linux, Windows, and WSL — only the install path differs.

npm install -g @techsologic/unolock-agent unolock-agent --help unolock-agent register '<agent-key-url>' '<pin>' unolock-agent list-spaces unolock-agent get-current-space

Exact steps

  1. Install the CLI with npm install -g @techsologic/unolock-agent.
  2. Run unolock-agent --help to confirm the install and inspect the available commands.
  3. Ask the user for the one-time UnoLock Agent Key URL and the PIN. The user creates these in the Safe web app.
  4. Run unolock-agent register '<agent-key-url>' '<pin>'. On a fresh host the first start may take longer because local cryptographic code may need to be compiled.
  5. The one-time URL is consumed. From now on the local agent uses its registered device-bound credential.
  6. Use the CLI directly: unolock-agent list-spaces, unolock-agent get-current-space, unolock-agent file-upload ./report.pdf, etc.
  7. If UnoLock asks for the PIN again later, set it with unolock-agent set-pin '<pin>'. Keep the PIN only in process memory when possible.

Common commands after registration

# inspect what you can see unolock-agent list-spaces unolock-agent get-current-space unolock-agent list-records # read and write notes unolock-agent read-note '<name>' unolock-agent create-note '<name>' '<text>' unolock-agent update-note '<name>' '<text>' # checklists unolock-agent toggle-checklist-item '<list>' '<item>' # files in current Space unolock-agent file-upload ./local.pdf unolock-agent file-download local.pdf

Notes and gotchas

  • The supported install path is the npm-provided binary. Install Node/npm first if the host does not already have it.
  • Don't persist the PIN to disk. Pass it on stdin or with set-pin at runtime.
  • The agent re-asks for the PIN after restart unless the UnoLock process stayed alive.
  • If register fails, check that the URL was issued for a live Agent Key the user has not yet rotated or revoked.
  • file-upload requires --force to overwrite a same-name file already in the current Space.