CLI Quick Start

Let’s run your first AI agent with gadgets from the command line.

Your First Completion

The simplest way to use llmist is the complete command:

    npx @llmist/cli complete "What is the capital of France?"

You’ll get a streaming response:

The capital of France is Paris.

Running an Interactive Agent

The agent command runs an AI agent that can use tools (gadgets):

    npx @llmist/cli agent "What time is it in Tokyo?"

When running in a terminal (both stdin and stdout are TTY), the agent automatically uses TUI mode with an interactive interface featuring expandable blocks, keyboard navigation, and live streaming.

Built-in Gadgets

The CLI includes three built-in gadgets for agent-user communication:

Gadget	Purpose
AskUser	Ask the user a question and wait for their response
TellUser	Display important messages (info, success, warning, error)
Finish	Signal that the agent has completed its task

These are registered automatically. Use --no-builtins to disable them.

Creating a Local Gadget

Create a custom gadget for your agent:

Create a gadgets directory
Terminal window
```
mkdir gadgets
```

Create a gadget file

import { Gadget, z } from 'llmist';

export default class ArcadeHighScore extends Gadget({
  description: 'Check or record high scores on the arcade cabinet',
  schema: z.object({
    game: z.enum(['pac-man', 'galaga', 'donkey-kong']),
    action: z.enum(['check', 'record']),
    initials: z.string().length(3).optional(),
    score: z.number().optional(),
  }),
}) {
  execute(params: this['params']): string {
    if (params.action === 'check') {
      return `High scores for ${params.game}: AAA-999999, BBB-888888, CCC-777777`;
    }
    return `${params.initials} recorded ${params.score} on ${params.game}!`;
  }
}

Run the agent with your gadget

    npx @llmist/cli agent --gadgets ./gadgets/arcade.ts \
      "Check the high scores for Pac-Man"

Your directory structure:

Directorygadgets/
- arcade.ts
package.json

Piping and Automation

The CLI integrates with Unix pipelines:

    # Summarize a file
    cat README.md | npx @llmist/cli complete "Summarize this document"

    # Code review
    cat src/main.ts | npx @llmist/cli complete "Review this code for bugs"

    # Process multiple files
    find src -name "*.ts" -exec cat {} \; | \
      npx @llmist/cli complete "Find potential security issues"

Choosing a Model

Specify the model with --model or -m:

    # Use Claude Sonnet
    npx @llmist/cli complete -m sonnet "Explain quantum computing"

    # Use GPT-5
    npx @llmist/cli complete -m gpt5 "Write a haiku about coding"

    # Use Gemini Flash (fast and cheap)
    npx @llmist/cli complete -m flash "What is 2 + 2?"

Next Steps

CLI Reference - Learn all available commands
Configuration - Set up custom commands
Writing Gadgets - Create powerful tools
TUI Mode - Master the interactive interface