# Output Formats

tdx supports multiple output formats for query results and command outputs.

## Format Options

| Option | Description |
|  --- | --- |
| (default) | Human-readable table (vertical layout for single objects) |
| `--table` | Horizontal table layout (forces table even for single objects) |
| `--json` | Readable JSON array |
| `--jsonl` | JSON Lines (one object per line) |
| `--tsv` | Tab-separated values |


## Table Format (Default)

Human-readable ASCII table with column types and row counts:


```bash
tdx query "SELECT name, age FROM users LIMIT 2"
```


```
┌────────┬─────┐
│  name  │ age │
│ string │ int │
├────────┼─────┤
│ Alice  │  25 │
│ Bob    │  30 │
├────────┴─────┤
│ 2 rows       │
└──────────────┘
```

Numbers are right-aligned, strings are left-aligned.

## JSON Format

Readable JSON array with newlines (no metadata):


```bash
tdx query "SELECT name, age FROM users LIMIT 2" --json
```


```json
[
  {"name":"Alice","age":25},
  {"name":"Bob","age":30}
]
```

Perfect for piping to `jq`:


```bash
tdx query "SELECT * FROM users" --json | jq '.[0]'
tdx query "SELECT * FROM users" --json | jq 'length'
```

## JSON Lines Format

One JSON object per line - ideal for streaming and line-by-line processing:


```bash
tdx query "SELECT name, age FROM users LIMIT 2" --jsonl
```


```
{"name":"Alice","age":25}
{"name":"Bob","age":30}
```

Process line by line:


```bash
tdx query "SELECT * FROM users" --jsonl | while read line; do
  echo "$line" | jq '.name'
done
```

## TSV Format

Tab-separated values with header row:


```bash
tdx query "SELECT name, age FROM users LIMIT 2" --tsv
```


```
name	age
Alice	25
Bob	30
```

## Color Output

tdx automatically adds ANSI colors to output in interactive terminals:

**Table format:**

- Table borders: Dark gray (dim)
- Column headers: Plain text
- Type row: Dim gray
- Data values: Plain text


**JSON format:**

- Keys: Blue
- Strings: Green
- Numbers: Cyan
- Booleans: Yellow
- Null values: Dim


### Automatic Detection

- Colors are enabled automatically when output is to an interactive terminal (TTY)
- Colors are disabled automatically when:
  - Output is piped to another command
  - Output is saved to a file with `--output`
- Respects the `NO_COLOR` environment variable


### Manual Control


```bash
# Force colors on (even when piping or saving to file)
tdx databases --color

# Disable colors (even in interactive terminal)
tdx databases --no-color

# Disable colors via environment variable
NO_COLOR=1 tdx databases
```

## Interactive Table Navigation

When viewing table output in an interactive terminal, tdx automatically pipes output through `less` for easy navigation:

| Key | Action |
|  --- | --- |
| `q` | Quit and return to terminal |
| `↑` / `↓` | Scroll up/down one line |
| `Space` | Scroll down one page |
| `b` | Scroll up one page |
| `←` / `→` | Scroll left/right (for wide tables) |
| `/pattern` | Search forward |
| `n` / `N` | Repeat search forward/backward |
| `g` / `G` | Go to first/last line |


Less pagination is disabled when:

- Output is piped to another command
- Output is saved to a file with `--output`
- Using non-table formats (JSON, JSONL, TSV)