| name | unicli-claude-code |
| description | Make Uni-CLI reliable when invoked from Claude Code. MANDATES JSON-in channels (stdin / --args-file) for any payload containing quotes, emoji, newlines, or inline JSON — shell-quoted invocations hit TC0 circuit limits and drop to <50% success above ICS=4. Also covers --describe introspection and next_actions-driven navigation.
|
| version | 1.2.1 |
| depends-on | ["human-writing"] |
| triggers | ["unicli","ics","args-file","stdin-json","quoted payload","emoji in query"] |
Uni-CLI × Claude Code — Reliable Invocation
TL;DR — If the payload contains ANY of: quotes, emoji, newlines, JSON,
non-ASCII, or is longer than ~60 chars, PIPE IT. Never inline.
Why this skill exists
Transformers live in TC0. Matching balanced " and ' pairs with arbitrary
nesting is a mod-2 state-tracking problem that TC0 cannot solve in constant
decode depth. Empirically, top LLMs land <43% on 0→1 CLI generation
(CLI-Tool-Bench arXiv:2604.06742) and 62% of agent-tool bugs cluster at the
tool-invocation / execution stages (arXiv:2603.20847).
Uni-CLI gives you THREE invocation channels. One of them (shell-args) inherits
the TC0 bottleneck. The other two do not.
The decision rule
| If the payload has … | Use channel |
|---|
| Only ASCII, no quotes, <60 chars | shell OK |
| Any quote or backslash | stdin-JSON |
| Emoji / CJK / non-ASCII | stdin-JSON |
| Newlines or inline JSON | stdin-JSON |
| Being reused across multiple invocations | --args-file |
When unsure → stdin-JSON. It never makes things worse.
The three channels
1 — stdin-JSON (preferred for complex payloads)
echo '{"query": "she said \"hi\" 🎉", "limit": 10}' | unicli twitter search
- Uni-CLI auto-detects non-TTY stdin whose body starts with
{
- Precedence: stdin-JSON >
--args-file > shell flags > defaults
- Works for EVERY command — no per-adapter opt-in needed
2 — --args-file (preferred when payload is reused)
cat > /tmp/q.json <<'EOF'
{ "query": "machine learning", "limit": 20, "locale": "en_US" }
EOF
unicli arxiv search --args-file /tmp/q.json
- Absolute paths recommended
- JSON only (YAML and TOML deliberately not supported — minimize format ambiguity)
3 — shell args (only for trivial payloads)
unicli hackernews top --limit 5
Fine when every value is ASCII, no quotes, no emoji.
Runtime introspection — unicli describe
Before invoking any unfamiliar command, run:
unicli describe <site> <command>
You get back a JSON object containing:
args_schema — JSON Schema draft-2020-12 for the argument bagexample_stdin — a realistic JSON body you can modify and pipechannels — the three invocation templatesnext_actions — hints for what to run next
This replaces reading docs. The CLI is the documentation.
The response envelope (v2)
Every successful call returns:
{
"ok": true,
"schema_version": "2",
"command": "twitter.search",
"meta": { "duration_ms": 847, "count": 10, "surface": "web" },
"data": [ ... ],
"error": null,
"next_actions": [
{ "command": "unicli describe twitter search", "description": "…" },
{ "command": "unicli twitter search --args-file <path.json>", "description"
Errors return ok: false with a structured error object (adapter_path,
step, suggestion) and failure-classified next_actions. unicli repair
appears only for established adapter-drift classes and verifies an edit; it
never edits automatically. If you see invalid_input from the hardening layer,
the arg bag tripped a safety check — read error.suggestion for the exact fix.
--dry-run — preview before committing
echo '{"query": "🎉", "limit": 5}' | unicli twitter search --dry-run
Prints the resolved ArgBag, the source channel, and the pipeline step count
without touching the network / filesystem. Use this whenever you want to
confirm the agent built the payload correctly.
Common failure modes → fixes
| Symptom | Root cause | Fix |
|---|
invalid_input: control characters | Embedded 0x01..0x1F in a string arg | Strip control chars; use \t \n \r only |
invalid_input: path escapes CWD | ../ or absolute path outside $HOME | Keep outputs inside cwd or $HOME/.unicli |
invalid_input: id contains URL punctuation | You pasted a full URL as a resource id | Strip the ?, #, or %XX sequences |
| Command appears to run but gets wrong args | Shell ate your quotes | Switch to stdin-JSON |
Unexpected shell expansion ($HOME, `) | Bash interpolated your payload | Single-quote, or better, use stdin-JSON |
Recipes
Search with a complex query
printf '%s\n' '{"query": "large language models \"emergent\" behaviour", "limit": 25}' \
| unicli arxiv search
Multi-arg desktop command
cat > /tmp/render.json <<'EOF'
{ "scene": "/Users/me/project/main.blend", "output_dir": "~/renders", "frame_start": 1, "frame_end": 240 }
EOF
unicli blender render --args-file /tmp/render.json
Debug-first workflow
unicli describe youtube transcript
echo '{"url": "https://…"}' | unicli youtube transcript --dry-run
echo '{"url": "https://…"}' | unicli youtube transcript
Version contract
- v0.214.0+ required for stdin-JSON auto-detect,
--describe, and consistent MCP tool discovery metadata
- v0.213.1 or earlier agents should fall back to
unicli schema <site> <cmd>
and explicit -- flag args
