Skip to content

README.md

Latest commit

 

History

History
95 lines (73 loc) · 3.2 KB

README.md

File metadata and controls

95 lines (73 loc) · 3.2 KB
Raw

picoclaw-cli

picoclaw-cli

A terminal-first remote CLI for PicoClaw.

Usage

go run . \
  -url ws://your-pico-host:18790/pico/ws \
  -token your-pico-token

Install

go install github.com/afjcjsbx/picoclaw-cli@latest

Then run:

picoclaw-cli \
  -url ws://your-pico-host:18790/pico/ws \
  -token your-pico-token

If picoclaw-cli is not on your PATH, run it from Go's default bin directory:

~/go/bin/picoclaw-cli \
  -url ws://your-pico-host:18790/pico/ws \
  -token your-pico-token

The -url flag must be a complete WebSocket URL, including ws:// or wss://. Use a host name or IP address only; SSH-style values like user@host are not valid here.

The client opens a WebSocket session, sends message.send, and renders message.create / message.update replies in the terminal. It separates normal assistant output from structured tool activity and, optionally, structured thought messages. Assistant replies are rendered as terminal-friendly Markdown, including headings, lists, links, tables, and code blocks.

Project layout

  • main.go lets go install github.com/afjcjsbx/picoclaw-cli@latest work from the module root
  • cmd/picoclaw-cli contains the executable entrypoint
  • pkg/cli contains the reusable CLI and TUI logic

Flags

Flag Default Description
-url $PICO_REMOTE_URL Remote Pico WebSocket URL
-token $PICO_REMOTE_TOKEN Pico auth token
-session random UUID Session id to reuse between runs
-token-query false Send token as ?token=... instead of Authorization: Bearer ...
-ping 25s Client ping interval
-mouse false Capture the mouse for wheel scroll and drag-to-copy in the TUI; disables native terminal text selection
-show-thoughts false Show structured thought messages
-tools true Enable structured tool call / tool feedback panels
-show-tools true Alias for -tools
-hide-tools false Start with tool panels hidden
-compact-tools false Show tool activity as compact headers only, without payload details

By default the TUI leaves mouse handling to your terminal so text remains selectable and copyable. Start with -mouse only if you want wheel scrolling and drag-to-copy inside the app instead.

Interactive commands

  • Up/down arrows browse saved input history between sessions (last 100 entries)
  • As you type a local /command, matching suggestions appear in the prompt
  • Tab autocompletes local /commands and toggle values like on/off
  • Text selection and copy use your terminal's native behavior by default
  • /help shows the available commands
  • /status shows URL, session, and display toggles
  • /session prints the current session id
  • /thoughts on|off toggles structured thought visibility
  • /tools on|off toggles tool visibility
  • /clear clears the screen and redraws the header
  • /quit exits

Tailscale + SSH tunnel example

If the gateway on the Raspberry is only listening on 127.0.0.1, tunnel it:

ssh user@your-tailnet-host.ts.net -L 18790:127.0.0.1:18790
picoclaw-cli -url ws://127.0.0.1:18790/pico/ws -token your-pico-token