iq

iq

Intelligent Query is a lightweight command-line LLM-powered file processor.

Intelligent Query iq is a lightweight command-line LLM-powered file processor. The tool is designed to simplify running LLM-powered agents in the batch against mounted file systems, whether they are simple prompting agents or more complex system that dynamically direct their own processes and tool to accomplish task.

• Features
• Installation
• Quick Start
• Usage
  • Prompt Engineering
• Examples
  • Basic usage
  • Processing file
  • Basic agent
  • Processing files with agent
  • Classification
  • Processing large files
  • Functions, Tools and Commands
  • Working with AWS S3
  • STDIN/STDOUT
• How To Contribute
• License

Features

• Apply prompt-based agents to files within a directory.
• Execute workflow-driven tools on directory-based files.
• Enable LLMs to utilize Bash, Golang, and Python for executing tasks.
• Support prompt templates and meta-prompting (prompts generated dynamically by the LLM).
• Enable STDIN/STDOUT for shell scripting integration.
• Support OpenAI, OpenAI-compatible APIs, AWS Bedrock, and LM Studio as LLM backends.

Installation

Install utility using either from Homebrew (MacOS) or GitHub Binary Releases (other platforms).

## Install using brew
brew tap fogfish/iq https://github.com/fogfish/iq
brew install -q iq

## use `brew upgrade` to upgrade to latest version 

Alternatively, install from source code, it requires Golang 1.24

go install github.com/fogfish/iq@latest

Before using iq, you need to configure it with access to an LLM provider. The tool supports multiple backends, including Amazon Bedrock, OpenAI, OpenAI-compatible APIs, and local LM Studio instances. The tool keeps the config at the .netrc file that generally resides in the user's home directory.

It is your responsibility to obtain access to LLMs either creating the necessary accounts or installed any required software (such as LM Studio), and verified access to the target model.

Use following commands to autoconfig .netrc record.

iq config --bedrock
iq config --lmstudio
iq config --openai <secret-key>

[!TIP] My personal recommendation is usage of Amazon Bedrock.

Quick Start

echo "What are the colors of rainbow?" | iq tell

[!TIP] use -m, --llm flags to override the default model

Usage

iq help

Available Commands:
  ask         process files in mounted dir with LLM
  config      configure utility
  draft       generate prompt template
  run         process files in mounted dir with LLM agent
  tag         classify files in the current directory using LLM
  task        execute LLM-agent with prompt instructions
  tell        send a prompt to LLM

Flags:
  -c, --config string   config profile at ~/.netrc about LLM provider (default "iq")
      --input string    override prompt input
  -m, --llm string      overrides LLM model defined at ~/.netrc
  -p, --prompt string   path to prompt yaml file

Use "iq [command] --help" for more information about a command.

Prompt Engineering

Prompts are a core component of how the iq utility operates. It expects prompts to be defined in YAML files, with the prompt key containing the actual prompt text.

[!TIP] TELeR framework — a practical taxonomy that breaks prompts into clear components: Task, Environment, Learner, and Response. This approach helps you craft reusable prompts by clearly defining goals, constraints, tone, and expected outputs. Use it to improve prompt quality, automate workflows, and ensure consistent LLM behavior across files and tasks.

Use iq draft command to create an empty structured prompt YAML file:

prompt: |
  [Describe the task and goals clearly and concisely].
  
  Guidelines:
    (1) [High-level principles or approach to follow.]
    (2) ...

  Strictly adhere to the following requirements when generating a response.
  Do not deviate, ignore, or modify any aspect of them:
    1. [Concrete requirement]
    2. [Another specific rule]
    ...

  Example Input:
  [Show an example of what the input might look like.]

  Expected Output:
  [Demonstrate the ideal format or structure of the response.]

  Additional Context:
    - [Relevant detail #1]
    - [Constraint or domain knowledge #2]
    - ...

  Input:
    [Insert the actual input here]

iq support prompt templating throught structured input key and Golang templating syntax.

input:
  name: rainbow

prompt: |
  What are the colors of {{.name}}?

In addtion, you can "try" to force LLM responding in JSON and build reusable prompt via include directive.

[!TIP] Meta-prompting is possible as well. The command below uses input text to generate a prompt

echo "What are the colors of rainbow?" | iq draft

Examples

Basic usage

iq tell send a standalone prompt and receive an immediate response, ideal for asking questions, drafting text, or running quick ideas past the model.

For example, running the prompt What are the colors of the rainbow

iq tell -p ./examples/prompt/01_basic.yml

Processing file

iq ask command treats a mounted directory of files as a processing queue—reading from an input directory, applying LLM-powered prompts to each file's content, and writing the results to an output directory. This batch-oriented processing is ideal for transformation, summarization or enhanced file processing at scale—with minimal setup and full traceability of inputs and outputs.

For example, running the prompt What are the colors of the thing over files containing "earth", "sun", etc would produce the color pallete about each concept.

iq ask -p ./examples/prompt/05_overfile.yml -d ./examples/prompt/doc -o /tmp

[!IMPORTANT] Use --mutable flag to remove input file right after it is processed. This controversial advice allows a queue-like system implementation to deal with errors. Use this option with caution — it modifies your input data and is best suited for temporary or disposable file queues.

Basic agent

We assume LLM-powered agent is a system that dynamically direct their own processes and available tool to accomplish task. Unlike a single prompt, a workflow allows the model to reason through multiple steps — such as reading, generating, modifying, and combining files — to accomplish a complex goal. Each step builds on the last, forming a coherent process that mimics how a human might complete a task using a shell or scripting environment.

For example, a workflow might involve generating content into files, transforming or replacing parts of that content, aggregating results, and applying formatting — all before producing a final output. By giving the LLM both a plan and access to command-level operations, workflows unlock a higher level of automation and creativity within your file system.

iq task empowers LLMs external tools, see Functions, Tools and Commands

For example, the task about colors.

iq task -p ./examples/task/01_basic.yml

Processing files with agent

iq run command treats a mounted directory of files as a processing queue—reading from an input directory, evaluating agent with each file's content, and writing the results to an output directory.

For example, running the prompt What are the colors of the thing over files containing "earth", "sun", etc would produce the color pallete about each concept.

iq run -p ./examples/task/02_processor.yml -d ./examples/prompt/doc -o /tmp

Classification

iq tag command uses an LLM to classify files based on their content and organize them accordingly. It processes each file, runs a prompt designed to extract metadata or labels (e.g., category, topic, sentiment, priority), and returns a structured response — typically in JSON. This metadata is used to move or copy files into specific directories, effectively sorting your input set into meaningful buckets. iq tag is ideal for organizing large, unstructured datasets, triaging documents, or preparing inputs for downstream workflows.

iq tag -p ./examples/prompt/05_overfile.yml -d ./examples/prompt/doc -o /tmp

Processing large files

iq provides smart input splitting to ensure files fit within the context window limits of LLMs. By default, it includes the largest possible portion of the file directly in the prompt. Splitting behavior is configurable — you can divide input by sentences, paragraphs, or fixed-size chunks.

iq help

  --splitter string         split input file into sentence, paragraph or chunk (default "none")
  --splitter-chars string   sequence of charates used by splitter as delimiter
  --splitter-chunk int      chunk size for splitter (default 1024)

Sentences: A sentence is defined as a punctuation mark (., !, or ?) followed by a whitespace character. The default punctuation marks are overwritten with --splitter-chars flag.

iq tell \
  --splitter sentence --splitter-chars . \
  ...

Paragraphs: A paragraph is defined as a block of text separated by an empty line (essentially using \n\n as delimiter). The default delimiter is overwritten with --splitter-chars flag.

iq tell \
  --splitter paragraph --splitter-chars $'\x0a\x0a' \
  ...

Fixed chunks: A fixed chunk has a defined size limit, which is extended to include the end of the nearest sentence (it prevents loss of context). The chunk size is configured with --splitter-chunk flag and --splitter-chars are used to define punctuation marks similar to sentence split.

iq tell \
  --splitter chunk --splitter-chunk 4096 \
  ...

Functions, Tools and Commands

iq enables integration with external tools through an MCP-like approach. To ensure reliable tool invocation and consistent request processing, deterministic control is essential. This necessitates access to the model’s latent generation capabilities. Use either AWS Bedrock API or OpenAI. My personal preferences is us.anthropic.claude-3-7-sonnet-20250219-v1:0

iq includes built-in tools for Bash, Golang, and Python (which must be installed in your environment) to accomplish defined tasks. Using these tools is straightforward—just declare them in the registry within the prompt file.

registry:
  - bash
  - python
  - golang

The tool support is fully extensible. To add a custom tool, simply declare it in the registry using the following format, all parameters are mandatory:

  - 
    # Unique name of the tool, used by the LLM to reference and invoke it
    name: weather
    # Command-line syntax template; placeholders (e.g., {{.city}}) are replaced with LLM-provided values 
    syntax: weather --city {{.city}}
    # Explain what the tool does to LLM
    about: Queries weather in city at given date.
    # Input parameters the tool accepts
    properties:
      - 
        # Name of the parameter expected by the tool
        name: city
        # The type of the parameter
        type: string
        # Explain the purpose of the parameter to LLM
        about: name of the city to query weather.

Working with AWS S3

iq supports both local file system and AWS S3 buckets. Use s3:// prefix to direct the utility (e.g. s3://bucket/path).

echo "What ..." | iq ask -d s3://my/example -o s3://my/result`

STDIN/STDOUT

id enables STDIN/STDOUT for shell scripting integration.

• It ONLY reads prompt from STDIN unless -p flag is used.
• It output request of processing to STDOUT for draft, tell and task commands.

How To Contribute

iq is MIT licensed and accepts contributions via GitHub pull requests:

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License