简单LLM CLI

Very Quick Start

List the models on OpenRouter:

uvx llcat -u https://openrouter.ai/api -m

What about just the qwen ones?

uvx llcat -u https://openrouter.ai/api -m '*qwen3*'

What about their capabilities in JSON?

uvx llcat -u https://openrouter.ai/api -m '*qwen3*' --info | jq .

Sure. What about a different protocol, say ollama?

uvx llcat -u http://localhost:11434 -m '*qwen3*' --info | jq .

You might think "That's funny ... it looks the same."

Correct. Welcome to llcat.

All the abstraction without those pesky leaks.

----

llcat can:

• Use local or remote servers, authenticated or not.
• Store conversation history optionally, as a JSON file.
• Pipe things from stdin and/or be prompted on the command line.
• Do tool calling using the OpenAI spec and MCP STDIO servers.
• List and choose models, system prompts, and add attachments.

llcat's basic CLI parameters are also compatible with Simon Willison's llm.

Examples

Here's some examples of how to use llcat as a building block for many common use-cases:

• Transferrable Conversations
• Stateful Interaction
• Interactive Chat
• Structured Output
• Evals
• Tool Calling

Example: Transferrable Conversations

Because conversations, models and servers are decoupled, you can easily mix and match them at any time.

Here's one conversation, hopping across models and servers.

Start a chat with Deepseek:

$ llcat -u https://openrouter.ai/api \
        -m deepseek/deepseek-r1-0528:free \
        -c /tmp/convo.txt \
        -sk $(cat openrouter.key) \
        "What is the capital of France?"

Continue it with Qwen using MAS format:

$ llcat -u "https://openrouter.ai/api#m=qwen/qwen3-4b:free"
        -c /tmp/convo.txt \
        -sk $(cat openrouter.key) \
        "And what about Canada?"

And finish on the local network:

$ llcat -u http://192.168.1.21:8080 \
        -c /tmp/convo.txt \
        "And what about Japan?"

Since the conversation goes to the filesystem as easily parsable JSON you can use things like inotify or fuse and push it off to a vector search backend or modify the context window between calls.

Example: Adding State

llcat's explicit syntax means lots of things are within reach.

For instance simple wrappers can be made custom to your workflow.

Here's a way to store state with environment variables to make invocation more convenient:

llf()        { llc "$@" 2> >(jq . >&2) | examples/spinner sd }
llc()        { llcat -m "$LLC_MODEL" -u "$LLC_SERVER" -sk "$LLC_KEY" "$@" }
llc-model()  { LLC_MODEL=$(llcat -m  -u "$LLC_SERVER" -sk "$LLC_KEY" | fzf) }
llc-server() { LLC_SERVER=$1 }
llc-key()    { LLC_KEY=$1 }

And now you can do things like this:

$ llc-server http://192.168.1.21:8080
$ llc "write a diss track where the knapsack problem hates on the towers of hanoi"

And what's that llf at the top? That uses jq to pretty print the errors and streamdown to pretty print the output along with a simple program to display a spinner while you wait.

There's no configuration files to parse or implicit states to manage.

Example: Interactive Chat

A conversation interface is also quick:

```shell #!/usr/bin/env bash

Example: Structured Output

Using the schema feature you can pass json in to enforce a schema. Try something like

$ llcat -u http://localhost:11434 -sc examples/schema.json "give me a person"

Example: Evals

Running the same thing on multiple models and assessing the outcome is straight forward. Here we're using ollama

pre="llcat -u http://localhost:11434"
for model in $($pre -m); do
   $pre -m $model "translate 国際化がサポートされています。to english" > ${model}.outcome
done

You can use patterns like that also for testing tool calling completion. Here's a bigger example: a humor eval to see if models know a funny joke when they see one

If an error happens contacting the server, you get the request, response, and a non-zero exit.

Try this to see what that looks like

uvx llcat -u fakecomputer

Example: Tool calling

The examples directory contains this music playing tool listing the contents of this album:

$ llcat -u http://127.1:8080 -tf tool_file.json -tp tool_program.py "what mp3s do i have in my ~/mp3 directory"
{"level": "debug", "class": "toolcall", "message": "request", "obj": {"id": "iwCGjcRic8GAFB2jUvBUOeF9NNrldfxz", "type": "function", "function": {"name": "list_mp3s", "arguments": {"path":"~/mp3"}}}}
{"level": "debug", "class": "toolcall", "message": "result", "obj": ["Elektrobopacek - Towards the final Battle.mp3", "Elektrobopacek - Escape the Labyrinth.mp3", "Elektrobopacek - Journey to the misty Lands.mp3", "Elektrobopacek - Mistral Forte.mp3", "Elektrobopacek - Leaving Spaceport X-19.mp3", "Elektrobopacek - Dracula Rising.mp3"]}
Here are the MP3 files in your `~/mp3` directory:

1. **Elektrobopacek - Towards the final Battle.mp3**
2. **Elektrobopacek - Escape the Labyrinth.mp3**
3. **Elektrobopacek - Journey to the misty Lands.mp3**
4. **Elektrobopacek - Mistral Forte.mp3**
5. **Elektrobopacek - Leaving Spaceport X-19.mp3**
6. **Elektrobopacek - Dracula Rising.mp3**

Would you like to play any of these? Just share the filename, and I can play it for you! 🎵

In this example you can see how nothing is hidden so if the model makes a mistake it is immediately identifiable.

The debug JSON objects are sent to stderr so routing it separately is trivial.

Usage

Now it's your turn.

usage: llcat [-h] [-su SERVER_URL] [-sk SERVER_KEY] [-m [MODEL]]
             [-s SYSTEM] [-c CONVERSATION] [-sc SCHEMA]
             [-cr CONVERSATIONRO] [-mf MCP_FILE] [-tf TOOL_FILE]
             [-pr PROTO] [-ps] [-tp TOOL_PROGRAM] [-to TIMEOUT] [-a ATTACH]
             [-bq BE_QUIET] [-nw] [--curlify] [--version] [--info [INFO]]
             [user_prompt ...]

llcat is /usr/bin/cat for LLMs. 

        🐱 Me-wow! 

https://github.com/day50-dev/llcat

positional arguments:
  user_prompt           Your prompt

options:
  -h, --help            show this help message and exit
  -su, -u, --server_url SERVER_URL
                        Server URL (e.g., http://::1:8080). Also supports MSA
                        format
  -sk, -k, --server_key SERVER_KEY
                        Server API key for authorization
  -m, --model [MODEL]   Model to use (or list models if no value)
  -s, --system SYSTEM   System prompt
  -c, --conversation CONVERSATION
                        Conversation history file (r/w)
  -sc, --schema SCHEMA  Set a schema to force structured output
  -cr, --conversationro CONVERSATIONRO
                        The readonly conversation input (ro)
  -mf, --mcp_file MCP_FILE
                        MCP file to use
  -tf, --tool_file TOOL_FILE
                        JSON file with tool definitions
  -pr, --proto PROTO    Protocol to use (ollama, openai, auto)
  -ps, --ps             Currently running model (if supported)
  -tp, --tool_program TOOL_PROGRAM
                        Program to execute tool calls
  -to, --timeout TIMEOUT
                        Timeout in seconds for the read
  -a, --attach ATTACH   Attach file(s)
  -bq, --be_quiet BE_QUIET
                        Make it shutup about things
  -nw, --no_wrap        Do not wrap inputs in <xml-like-syntax>
  --curlify             Write curl equivalents of calls to stdout
  --version             show program's version number and exit
  --info [INFO]         Get the info for a model

We're excited to see what you build.

Brought to you by DA`/50: Make the future obvious.

We pick a file for the conversation or allow a user to pass it in with a CONV environment variable

conv=${CONV:-$(mktemp)} echo -e " Using: $conv\n"