claw — NanoPieLot CLI
claw is a Python CLI that sends prompts directly to a NanoPieLot agent container from the terminal. It reads registered groups from the NanoPieLot database, picks up secrets from .env, and pipes a JSON payload into a container run — no chat app required.
What it does
- Send a prompt to any registered group by name, folder, or JID
- Default target is the main group (no
-gneeded for most use) - Resume a previous session with
-s <session-id> - Read prompts from stdin (
--pipe) for scripting and piping - List all registered groups with
--list-groups - Auto-detects
containerordockerruntime (or override with--runtime) - Prints the agent's response to stdout; session ID to stderr
- Verbose mode (
-v) shows the command, redacted payload, and exit code
Prerequisites
- Python 3.8 or later
- NanoPieLot installed with a built and tagged container image (
nanopielot-agent:latest) - Either
container(Apple Container, macOS 15+) ordockeravailable inPATH
Install
Run this skill from within the NanoPieLot directory. The script auto-detects its location, so the symlink always points to the right place.
1. Copy the script
mkdir -p scripts
cp ".github/skills/claw/scripts/claw" scripts/claw
chmod +x scripts/claw
2. Symlink into PATH
mkdir -p ~/bin
ln -sf "$(pwd)/scripts/claw" ~/bin/claw
Make sure ~/bin is in PATH. Add this to ~/.zshrc or ~/.bashrc if needed:
export PATH="$HOME/bin:$PATH"
Then reload the shell:
source ~/.zshrc # or ~/.bashrc
3. Verify
claw --list-groups
You should see registered groups. If NanoPieLot isn't running or the database doesn't exist yet, the list will be empty — that's fine.
Usage Examples
# Send a prompt to the main group
claw "What's on my calendar today?"
# Send to a specific group by name (fuzzy match)
claw -g "family" "Remind everyone about dinner at 7"
# Send to a group by exact JID
claw -j "120363336345536173@g.us" "Hello"
# Resume a previous session
claw -s abc123 "Continue where we left off"
# Read prompt from stdin
echo "Summarize this" | claw --pipe -g dev
# Pipe a file
cat report.txt | claw --pipe "Summarize this report"
# List all registered groups
claw --list-groups
# Force a specific runtime
claw --runtime docker "Hello"
# Use a custom image tag (e.g. after rebuilding with a new tag)
claw --image nanopielot-agent:dev "Hello"
# Verbose mode (debug info, secrets redacted)
claw -v "Hello"
# Custom timeout for long-running tasks
claw --timeout 600 "Run the full analysis"
Troubleshooting
"neither 'container' nor 'docker' found"
Install Docker Desktop or Apple Container (macOS 15+), or pass --runtime explicitly.
"no secrets found in .env"
The script auto-detects your NanoPieLot directory and reads .env from it. Check that the file exists and that your NanoPieLot install is configured for the channels or tools you expect to use.
Container times out
The default timeout is 300 seconds. For longer tasks, pass --timeout 600 (or higher). If the container consistently hangs, check that your nanopielot-agent:latest image is up to date by running ./container/build.sh.
"group not found"
Run claw --list-groups to see what's registered. Group lookup does a fuzzy partial match on name and folder — if your query matches multiple groups, you'll get an error listing the ambiguous matches.
Container crashes mid-stream
Containers run with --rm so they are automatically removed. If the agent crashes before emitting the output sentinel, claw falls back to printing raw stdout. Use -v to see what the container produced. Rebuild the image with ./container/build.sh if crashes are consistent.
Override the NanoPieLot directory
If claw can't find your database or .env, set the NANOPIELOT_DIR environment variable:
export NANOPIELOT_DIR=/path/to/your/nanopielot
