treease-cli 1.2.1

Command-line interface for querying, transforming, and previewing structured documents with Treease
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

# treease-cli

`treease-cli` evaluates, transforms, formats, converts, and previews structured
documents from the terminal. It uses the same Treease core as the Web workspace
and is designed for JSON, YAML, TOML, CSV, and other supported structured
formats.

## Installation

Install the latest published CLI with Cargo:

```bash
cargo install treease-cli
```

Check the installed version and the complete generated help with:

```bash
treease --help
treease help --format json
```

## Basic usage

The first positional argument is a Treease expression. The optional final
argument is an input file; when it is omitted, Treease reads standard input.

```bash
# Read a nested value from a YAML file.
treease '.services.api.url' config.yaml

# Read JSON from stdin and convert the result to YAML.
cat response.json | treease -o yaml '.'

# Select an input format and an output format explicitly.
treease -p yaml -o json '.' config.yaml

# Evaluate an expression without an input document.
treease --null-input '.hello = "world"'

# Write a result back to one input file.
treease --inplace '.version = "2"' package.json
```

The default expression is `.`. It returns the complete input document.

## Input and output options

| Option | Description |
| --- | --- |
| `-p, --input-format FORMAT` | Set the input format explicitly. |
| `-o, --output-format FORMAT` | Set the output format explicitly. |
| `-P, --prettyPrint` | Pretty-print the output. |
| `-I, --indent INDENT` | Set the output indentation width. |
| `-r, --unwrapScalar` | Print scalar results without a document wrapper. |
| `-N, --no-doc` | Disable YAML document separators. |
| `-i, --inplace` | Write the result back to the input file. Requires exactly one file. |
| `-n, --null-input` | Evaluate without reading a file or standard input. |
| `-e, --exit-status` | Exit with status 1 when the result is empty, null, or false. |

Use `treease formats list` to inspect the formats available in the installed
build. Use `-p` or `-o` when the file extension is missing or does not describe
the actual content.

## Web graph view

`treease web` evaluates one input document and opens a readonly Treease graph
view for the selected result:

```bash
treease web '.services.api' config.yaml
treease web '.' -
```

The command accepts one file path or `-` for standard input. It starts a
short-lived localhost data service and opens the configured Treease Web URL.
The Web graph view is readonly; use the normal `treease` command when the
result needs to be written or further transformed in the terminal.

## Operator and format discovery

The CLI exposes machine-readable discovery commands so scripts and tools can
inspect the installed capability set without duplicating the registry:

```bash
treease operators list
treease operators list --category string
treease operators get select
treease operators search map

treease formats list
treease formats get yaml
```

Add `--format json` to commands that support it:

```bash
treease operators list --format json
treease formats list --format json
```

## Common expression patterns

```bash
# Traverse a path.
treease '.services.api' config.yaml

# Select matching values.
treease '.users[] | select(.active == true)' users.json

# Convert a selected value.
treease -o yaml '.deployment' config.json

# Update a value in place.
treease --inplace '.metadata.version = "2026.07"' manifest.yaml
```

Use `treease operators list` and `treease operators get NAME` for the
installed operator summaries, syntax, examples, and limitations.

## Structured metadata

The command specification, operator catalog, and format catalog are exported
from the same source used by the CLI help output:

```bash
treease help --format json
treease operators list --format json
treease formats list --format json
```

This keeps generated documentation and tooling metadata aligned with the
actual parser and runtime capabilities.

## Error handling

Errors are written to standard error and the process exits with status `1`.
Use the command-specific help and discovery commands shown above when an
expression, format, operator, or input path is rejected.

## Project links

- Website: <https://treease.com>
- Source repository: <https://github.com/loggerhead/treease>
- CLI source: <https://github.com/loggerhead/treease/tree/main/apps/cli>
- Core crate: <https://crates.io/crates/treease-core>
- API documentation: <https://docs.rs/treease-cli>

## Local verification

```bash
cd apps/cli
cargo nextest run --locked --lib
bash tests/acceptance/run.sh
cargo doc --no-deps --lib
```