Getting Started¶

This guide covers the basics of using tmq to work with TOML files.

Basic Concepts¶

TOML Structure¶

TOML files use a simple, human-readable format:

# config.toml
title = "My Application"

[database]
host = "localhost"
port = 5432
enabled = true

[server]
host = "0.0.0.0"
port = 8080

[[users]]
name = "Alice"
role = "admin"

[[users]]
name = "Bob"
role = "user"

Query Syntax¶

tmq uses dot notation to access TOML values: - title → root-level keys - database.host → nested table values - users[0].name → array element access

First Steps¶

Check Installation¶

tmq --version
tmq --help

Basic Query¶

Create a test TOML file:

cat > config.toml << 'EOF'
title = "My App"
version = "1.0.0"

[database]
host = "localhost"
port = 5432
EOF

Query values:

# Get title
tmq '.title' config.toml
# Output: "My App"

# Get version
tmq '.version' config.toml
# Output: "1.0.0"

# Get database host
tmq '.database.host' config.toml
# Output: "localhost"

# Get database port
tmq '.database.port' config.toml
# Output: 5432

Display All Data¶

# Show entire file
tmq '.' config.toml

# Format as JSON
tmq '.' config.toml -o json

# Format as YAML
tmq '.' config.toml -o yaml

Common Patterns¶

Stdin Input¶

# Read from stdin
cat config.toml | tmq '.version'

# Use with other tools
echo 'version = "2.0.0"' | tmq '.version'

Error Handling in Scripts¶

#!/bin/bash
VERSION=$(tmq '.version' config.toml)
if [ $? -ne 0 ]; then
    echo "Error reading version from config.toml"
    exit 1
fi
echo "Version: $VERSION"

File Operations¶

# Check if file exists and is valid TOML
if tmq '.' config.toml > /dev/null 2>&1; then
    echo "config.toml is valid"
else
    echo "config.toml is invalid or missing"
fi

Next Steps¶

Now that you know the basics:

Query Operations: Learn advanced querying in Query Operations
Modifications: Learn to modify TOML files in Modification Operations
Validation: Check file validity in Validation & Comparison
Examples: See comprehensive examples in Examples

Quick Reference¶

Command	Description
`tmq '.key' file.toml`	Query a value
`tmq '.' file.toml`	Show entire file
`tmq '.' file.toml -o json`	Output as JSON
`cat file.toml \\| tmq '.key'`	Read from stdin
`tmq --validate file.toml`	Validate TOML syntax
`tmq --help`	Show help

Exit Codes¶

tmq uses standard exit codes: - 0: Success - 1: Parse/runtime error - 2: Usage error - 3: Security error - 4: File error