CLI Reference

Complete command-line reference for the tauq CLI tool.

Commands

tauq build

Parse Tauq Notation (.tqn) files to JSON.

Basic Usage

# Parse to stdout
tauq build data.tqn

# Parse to file
tauq build data.tqn -o output.json

# Parse from stdin
cat data.tqn | tauq build -
echo '!def User id name; 1 Alice' | tauq build -

Options

Flag Description Example
-o, --output Output file path -o out.json
--pretty Pretty-print JSON with 2-space indent --pretty
- Read from stdin cat file.tqn | tauq build -

Example

Input file users.tqn:

users.tqn tauq 
!def User id name email role
1 Alice "alice@example.com" admin
2 Bob "bob@example.com" user

Command:

tauq build users.tqn --pretty

Output:

[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com",
    "role": "admin"
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "bob@example.com",
    "role": "user"
  }
]

tauq format

Convert JSON to Tauq Notation. Automatically detects arrays of uniform objects and generates schemas.

Basic Usage

# Convert JSON file to Tauq
tauq format data.json -o data.tqn

# From stdin
echo '{"users":[{"id":1,"name":"Alice"}]}' | tauq format -

# Convert multiple files
tauq format api/*.json

Auto Schema Generation

The formatter intelligently detects arrays of objects and creates schemas automatically:

Input JSON:

{
  "users": [
    {"id": 1, "name": "Alice", "role": "admin"},
    {"id": 2, "name": "Bob", "role": "user"}
  ]
}

Output Tauq:

!def User id name role
---
users [
  !use User
  1 Alice admin
  2 Bob user
]

✨ Schema name "User" automatically derived from key "users" (singularized + PascalCase)

Options

Flag Description
-o, --output Output file path
- Read from stdin

tauq exec

Execute Tauq Query (.tqq) files for dynamic data generation and transformations.

Basic Usage

# Execute TQQ file
tauq exec pipeline.tqq -o output.json

# Safe mode (disable shell execution)
tauq exec pipeline.tqq --safe

# From stdin
cat template.tqq | tauq exec -

Options

Flag Description
-o, --output Output file path
--safe Disable shell execution (!emit, !run, !pipe)
--pretty Pretty-print output JSON

Example: Dynamic Data Generation

File pipeline.tqq:

pipeline.tqq tauq 
!set APP_NAME "MyService"
!set VERSION "1.0.0"

!emit sh -c 'echo "build_date \\"$(date +%Y-%m-%d)\\""'

app {
  name MyService
  version "1.0.0"
}

Command:

tauq exec pipeline.tqq --pretty

⚠️ Security Warning

TauqQ can execute arbitrary shell commands via !emit, !run, and !pipe directives.

Always use --safe mode when executing untrusted .tqq files. Safe mode disables all shell execution features.

tauq minify

Compress Tauq files to a single line for maximum token efficiency.

Basic Usage

# Minify a file
tauq minify data.tqn -o data.min.tqn

# From stdin
cat data.tqn | tauq minify -

Example

Input:

!def User id name email

1 Alice "alice@example.com"
2 Bob "bob@example.com"
3 Carol "carol@example.com"

Output:

!def User id name email; 1 Alice "alice@example.com"; 2 Bob "bob@example.com"; 3 Carol "carol@example.com"

Uses semicolon separators to put all records on one line. Perfect for embedding in prompts or minimizing token usage.

tauq validate

Check Tauq syntax without parsing to JSON. Useful for CI/CD pipelines and editor integrations.

Basic Usage

# Validate a file
tauq validate data.tqn

# Validate multiple files
tauq validate **/*.tqn

# From stdin
cat data.tqn | tauq validate -

Exit Codes

Code Meaning
0 Valid syntax
1 Syntax error

CI/CD Integration

# GitHub Actions example
- name: Validate Tauq files
  run: |
    find . -name "*.tqn" -exec tauq validate {} \\;
    if [ $? -ne 0 ]; then
      echo "Tauq syntax errors found!"
      exit 1
    fi

Installation

Via Cargo (Rust)

cargo install tauq

Requires Rust 1.70 or later. Install Rust from rustup.rs

From Source

git clone https://github.com/epistates/tauq.git
cd tauq
cargo build --release
# Binary is at target/release/tauq

Language Bindings

Use Tauq in Python, JavaScript, Go, and more.

View Bindings →

Syntax Guide

Learn the full Tauq notation syntax.

Read Guide →

Try the Playground

Convert JSON to Tauq interactively.

Open Playground →