@sheetxl/skills 0.0.0-stage → 0.8.0-beta.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,173 @@
1
+ ---
2
+ name: charts
3
+ description: "SheetXL charts: reading what a chart plots, inserting one, and editing it — type, data, title, legend, axes, series, points, data labels, trendlines, error bars — through the chart API, Office Scripts' names. Load when a task mentions a chart. Triggers on: chart, getCharts, IChart, series, axis, legend, data labels, trendline, error bars, plot, graph."
4
+ ---
5
+
6
+ # Charts — Read, Insert, Edit
7
+
8
+ > Part of the SheetXL skill suite. See the root `SKILL.md` for routing. Code below
9
+ > is run-context code (`scripting.md`): snippet form — no `await` needed on the
10
+ > statements shown as plain calls (every statement auto-awaits); `getCharts().add`
11
+ > returns a promise and is awaited like any other.
12
+
13
+ **In this file:** What a chart is here · Reading a chart · Inserting one ·
14
+ Editing: the chart, its series, axes, elements · What is refused · Verify
15
+
16
+ ## What a chart is here
17
+
18
+ A chart is a movable (`sheet.getMovables()`, type `chart`) whose content is an
19
+ `IChart`. It plots cells: every series states its name, categories and values as
20
+ formulas (`Data!$B$2:$B$7`), the way Excel's own dialog does. The API follows
21
+ Office Scripts' names (`getSeries`, `setChartType`, `getAxes().getValueAxis()`,
22
+ `getDataLabels`, `addChartTrendline`), so what you know from `ExcelScript.Chart`
23
+ carries over; VBA's names are noted where they differ.
24
+
25
+ Every setter writes exactly what Excel writes for the same change and is one step
26
+ to undo. A chart edited here opens in Excel as if Excel had made the edit.
27
+
28
+ ## Reading a chart
29
+
30
+ The reports already say what a chart plots: the sheet report's `Charts` section
31
+ lists each chart with `series`, `names`, `categories`; a chart's own report
32
+ (`renderMovable`) adds its title, legend, axes and the analysis on its series
33
+ (`reading.md`). For more, ask the chart:
34
+
35
+ ```typescript
36
+ const chart = sheet.getCharts().getItems()[0]; // or sheet.getCharts().getByName('Chart 2')
37
+ chart.getChartType(); // 'columnClustered', 'line', 'pie', 'combo', …
38
+ chart.getChartTitle(); // the text, a cell's text when it reads one
39
+ chart.getSeries().map(s => [s.getName(), s.getValuesFormula(), s.getCategoriesFormula()]);
40
+ chart.getAxes().getItems().map(a => [a.getKind(), a.getTitle().getText(), a.getNumberFormat()]);
41
+ chart.getLegend().getPosition(); // 'bottom' | 'right' | 'top' | 'left' | 'corner'
42
+ ```
43
+
44
+ A series' `getValuesRange()` is the cells, or `null` when the formula names
45
+ none (`#REF!`, a name, a literal `{1,2,3}`). A pivot chart (`getPivotSource()`)
46
+ states its table; its ranges are wherever the table last put its cells.
47
+
48
+ ## Inserting a chart
49
+
50
+ ```typescript
51
+ const chart = await sheet.getCharts().add('A1:D7', { type: 'line' });
52
+ ```
53
+
54
+ The cells are read by Excel's rules: a header row names the series, the first
55
+ column holds the categories, and the series are the columns unless there are more
56
+ columns than rows (`seriesBy: 'rows' | 'columns'` to say). `type` is any type
57
+ Excel's gallery offers — `columnClustered`, `columnStacked`, `columnStacked100`,
58
+ `bar…`, `line`, `lineMarkers`, `area…`, `pie`, `doughnut`, `xyscatter…`,
59
+ `bubble`, `radar…`, `stockVHLC`…, the 3-D forms (`3DColumnClustered`, `3DPie`…),
60
+ the surfaces, and the 2016 types (`waterfall`, `treemap`, `sunburst`, `histogram`,
61
+ `pareto`, `boxwhisker`, `funnel`, `regionMap`), which are made and saved as Excel
62
+ makes them but drawn as a placeholder for now. The chart is 5 by 3 inches in the
63
+ middle of the window unless `bounds` says otherwise.
64
+
65
+ ## Editing
66
+
67
+ ### The chart
68
+
69
+ ```typescript
70
+ chart.setChartType('lineMarkers'); // every series; a combo becomes one group
71
+ chart.setData('Data!A1:E7', 'columns'); // other cells, same formatting where series take their place
72
+ chart.setSeriesBy('rows'); // Switch Row/Column
73
+ chart.update({ title: 'Sales by Month', legend: { position: 'right' } });
74
+ chart.getTitle().setText('=Data!$A$1'); // a title that follows a cell
75
+ chart.setElement('legendTop'); // any Add Chart Element pick, by VBA's msoElement… name
76
+ chart.update({ style: { fill: '#F2F2F2', font: { family: 'Arial', size: 11 } }, roundedCorners: true });
77
+ chart.getDataTable().update({ visible: true, showLegendKey: true });
78
+ chart.getDataLabels().setVisible(true); // every series' labels
79
+ chart.getMovable().setBounds({ x: 480, y: 20, width: 480, height: 288 }); // px; placement is the movable's
80
+ ```
81
+
82
+ `update` takes several properties at once as one undo step. `setElement` takes
83
+ the element names of `MsoChartElementType` without the prefix, in lower camel
84
+ case: `chartTitleAboveChart`, `dataLabelOutsideEnd`, `primaryValueGridLinesMinor`,
85
+ `primaryCategoryAxisTitleBelowAxis`, `trendlineAddLinear`, `errorBarStandardError`,
86
+ `upDownBarsShow`, `dataTableWithLegendKeys`, …
87
+
88
+ ### Series and points
89
+
90
+ ```typescript
91
+ const s = chart.getSeries()[0];
92
+ s.update({ name: 'Total', values: 'D2:D7' });
93
+ s.setFormula('=SERIES(Data!$D$1,Data!$A$2:$A$7,Data!$D$2:$D$7,1)');
94
+ s.setChartType('line'); s.setAxisGroup('secondary'); // a combo
95
+ s.update({ style: { fill: '#FF0000', stroke: { width: 2 } }, gapWidth: 50, smooth: true });
96
+ s.getDataLabels().update({ visible: true, position: 'outsideEnd', numberFormat: '0.0', showPercentage: true });
97
+ s.getPoints()[2].update({ style: { fill: '#00B050' }, explosion: 20, hasDataLabel: true });
98
+ s.addChartTrendline('polynomial').update({ polynomialOrder: 3, showEquation: true, showRSquared: true });
99
+ s.getYErrorBars().update({ type: 'stDev', amount: 1 });
100
+ s.getMarker().update({ symbol: 'diamond', size: 8 });
101
+ chart.addSeries('East').update({ values: 'D2:D7' });
102
+ s.delete();
103
+ ```
104
+
105
+ A series' categories are shared by every series on its axis: setting them on one
106
+ sets them all (as Excel does). `setFormula` takes Excel's `=SERIES(name, categories,
107
+ values, order[, sizes])`, every part optional.
108
+
109
+ ### Axes
110
+
111
+ ```typescript
112
+ const value = chart.getAxes().getValueAxis(); // the primary; getChartAxis('value', 'secondary') for the other
113
+ value.update({ minimum: 0, maximum: 40, majorUnit: 10, minorUnit: 2, numberFormat: '#,##0', title: 'Units' });
114
+ value.update({ scaleType: 'logarithmic', logBase: 10, displayUnit: 'thousands', showDisplayUnitLabel: true });
115
+ value.update({ reversePlotOrder: true, crosses: 'maximum', majorTickMark: 'cross', tickLabelPosition: 'high' });
116
+ const category = chart.getAxes().getCategoryAxis();
117
+ category.update({ majorGridlines: true, textOrientation: 45, categoryNames: 'H2:I7', multiLevel: true });
118
+ category.update({ categoryType: 'dateAxis', baseTimeUnit: 'days', majorUnit: 1, majorTimeUnitScale: 'months' });
119
+ value.getTitle().update({ text: 'Units', textOrientation: 0, style: { font: { bold: true } } });
120
+ ```
121
+
122
+ `minimum`, `maximum` and the units read as the layout draws them and take
123
+ `'auto'` to be automatic again.
124
+
125
+ ### Elements
126
+
127
+ Every part of a chart is an element with a path, and the chart answers the path
128
+ with the same object for as long as the part is there:
129
+
130
+ ```typescript
131
+ chart.getElements().map(e => e.getPath()); // what the chart shows: 'title', 'axes/primary/value', 'series/0', …
132
+ const t = chart.getElement('axes/primary/value/title'); // null where there is none
133
+ t?.getElementType(); // 'axisTitle'
134
+ chart.getElement('series/0/points/2')?.getStyle?.()?.setFill('#00B050');
135
+ ```
136
+
137
+ Paths: `chartArea`, `title`, `legend`, `legend/entries/<n>`, `plotArea`,
138
+ `dataTable`, `axes/<primary|secondary>/<category|value|series>` (with `/title`,
139
+ `/majorGridlines`, `/minorGridlines`), `series/<key>` (with `/marker`,
140
+ `/dataLabels`, `/errorBars/<x|y>`, `/trendlines/<n>`, `/points/<n>`,
141
+ `/points/<n>/marker`, `/points/<n>/dataLabel`), `groups/<n>` (with
142
+ `/upDownBars`, `/hiLoLines`, `/dropLines`, `/seriesLines`). A series' key is its
143
+ `c:idx`; points, trendlines and groups go by their place, from 0. Each element
144
+ has a type flag (`isISeries`, `isIAxis`, `isITitle`, …) and, where it is drawn,
145
+ `getStyle()`: fill and line (`IShapeStyle`), and on a part with text (chart area,
146
+ title, axis title, legend, legend entry, axis, data labels, data table) also
147
+ `getStyle().getFont()` (`ITextBoxStyle`, `isITextBoxStyle`). There is no
148
+ `getFont()` on a part. The font is an `IFontStyle` (family, size, bold, italic,
149
+ underline, strike, color, letter spacing, baseline), the same interface a cell's
150
+ `range.getStyle().getFont()` answers, so the same code formats either; `update`
151
+ nests it the same way: `title.update({ style: { fill: 'white', font: { bold: true } } })`.
152
+ `chart.getStyle().getFont()` sets every text in the chart. A legend entry's fill
153
+ and line are the legend's; setting them throws. A theme font is the family
154
+ `'theme:body'` or `'theme:heading'`.
155
+
156
+ ## What is refused
157
+
158
+ Each refusal is an `ExpectedError` saying why; nothing is written.
159
+
160
+ - A 2016 type (waterfall, histogram, pareto, box and whisker, treemap, sunburst,
161
+ funnel, region map): its title, legend and type are edited; the rest is not yet,
162
+ and it is drawn as a placeholder.
163
+ - A pivot chart: it changes with its table.
164
+ - A property Excel refuses for the type: a trendline on a pie, drop lines on a
165
+ column chart, a bubble size label on a line, `setChartType` to a stock type.
166
+ - An address that is not one. A reference to cells that are gone (`#REF!`) is kept,
167
+ as Excel keeps it, and the series plots nothing.
168
+
169
+ ## Verify
170
+
171
+ Read back what you set — `chart.getChartType()`, `series.getValuesFormula()`,
172
+ `axis.getMinimum()` — and the chart's report (`renderMovable`). Saved to `.xlsx`, a
173
+ chart reads back as the same chart and opens in Excel without repair.
@@ -0,0 +1,287 @@
1
+ ---
2
+ name: cli
3
+ description: "SheetXL terminal commands: executing SDK code against a workbook file, grep, info, setup, and the interactive session. Flags (-e, -c, -f, -i, --out, --save, --json, --md.features), chaining scripts, shell composition, CI. Triggers on: npx sheetxl, sheetxl grep, sheetxl info, -e, -c, -f, --out, --save, --json, REPL, terminal, command line, automate."
4
+ ---
5
+
6
+ # CLI — Terminal Commands
7
+
8
+ > Part of the SheetXL skill suite. See the root `SKILL.md` for routing.
9
+ > How to *write* the code you run is `scripting.md`; this is how to invoke it.
10
+
11
+ **In this file:** The grammar · compile — typecheck without running · Large
12
+ workbooks — parsing repeats · Structured questions are one-liners · grep ·
13
+ Interactive sessions · Composition
14
+
15
+ | Command | Purpose |
16
+ |---|---|
17
+ | `sheetxl [options] [workbook]` | The main event: execute SDK TypeScript against a workbook — including every structured question. Return `getRegions()`, `getStats()`, a range, and the report renders. With no code, an interactive session. |
18
+ | `sheetxl info` | Read-only environment report: versions, skills, MCP status. Once per session. |
19
+ | `sheetxl setup` | Converge the environment (skills, engine, MCP registration) — consent at each step. |
20
+ | `sheetxl grep <pattern>` | Find cells by content or pattern. |
21
+ | `sheetxl compile <files…>` | Typecheck (and optionally emit) without executing. |
22
+
23
+ Zero-install: prefix any command with `npx -y` (`npx -y sheetxl info`).
24
+
25
+ ## The grammar
26
+
27
+ ```
28
+ sheetxl [options] [workbook]
29
+ ```
30
+
31
+ There is **no `run` verb** — the operation is the default, the way `duckdb -c
32
+ "<sql>" my.db` needs no verb. One rule decides the mode:
33
+
34
+ > Give it code and it runs, prints, and exits. Give it none and you get an
35
+ > interactive session.
36
+
37
+ ```
38
+ sheetxl -e "<code>" [workbook] # inline snippet
39
+ sheetxl -f <script.ts> [workbook] # script file; repeat -f to chain on the same workbook
40
+ sheetxl [workbook] < script.ts # code from stdin
41
+ sheetxl [workbook] # no code → interactive session
42
+ ```
43
+
44
+ The positional argument is the **workbook**, the same slot it fills in `grep`.
45
+ Code is never positional: it arrives through `-e`, `-f`, or stdin. Omit the
46
+ workbook and you get a blank one.
47
+
48
+ Prefer stdin (e.g. with a heredoc) over `-e` when the code is multi-line or
49
+ shell quoting gets awkward. **On PowerShell, make it the default** — a
50
+ single-quoted here-string piped in is literal, where `-e "…"` expands `$` and
51
+ backticks and dies on `!` the moment an inner quote breaks the outer string
52
+ (root `SKILL.md` has the form).
53
+
54
+ Flags:
55
+
56
+ ```
57
+ -e, -c <code> inline code, snippet or script; the result is rendered.
58
+ Repeatable (-c is an alias, for duckdb/python muscle memory)
59
+ -f <script> script file; repeatable, chained on the same workbook —
60
+ a chain renders the last one's result
61
+ -i, --interactive stay in an interactive session after the code runs
62
+ --out <file> write the workbook here; `-` writes it to stdout, for piping
63
+ --save write back to the workbook that was opened; naming a different
64
+ destination is `--out <file>`. With no input workbook, an error
65
+ --json the result as structured JSON, for piping (default is rendered text)
66
+ --no-delta omit the run delta: what a write changed, printed after the result
67
+ (`Changed:`, `Dependents:`, …). A read-only run prints none, and
68
+ neither does `--json`; a chain labels each target that wrote
69
+ --in.<key>=<value> format options for input (e.g. --in.csv.delimiter=";")
70
+ --out.<key>=<value> format options for output (e.g. --out.format=csv)
71
+ --md.<key>=<value> report options (--md.features=fill,borders, --md.mode=value)
72
+ -- <args…> forwarded to the run (in scope as `args`)
73
+ ```
74
+
75
+ `-v` prints the CLI, engine and node versions on one line; `sheetxl info` is the full handshake.
76
+ `-h` is a short help, `--help` the complete one.
77
+
78
+ Anything else beginning with `-` is an error, suggesting the flag you probably meant. A script's
79
+ own arguments go after `--` — there is no implicit passthrough.
80
+
81
+ `--md.<key>` configures the *report*, not the query — the expression already says what was asked
82
+ for — which is why it is grouped under `--md` the way input and output options are grouped under
83
+ `--in.*` and `--out.*`. `--md.features` is what makes a formatting audit readable on a heavily styled
84
+ sheet:
85
+
86
+ ```bash
87
+ sheetxl -e "wb.getWorksheet()" book.xlsx --md.features=fill,borders
88
+ sheetxl -e "wb.getWorksheet('Model')" book.xlsx --md.features=formula,error # the audit view of one sheet
89
+ ```
90
+
91
+ The other key is `mode` — `display` (number format applied) or `value` (full precision,
92
+ formatting stripped). An unknown key or feature is an error listing the whole vocabulary, checked
93
+ before the workbook is read. `--json` does not read these and says so rather than ignoring them.
94
+
95
+ **Those two are the whole surface: it selects, it does not size.** There is no option for a longer
96
+ report, because a longer report is never the answer — every listing that truncates names the query
97
+ that returns the rest, and the query is both cheaper and exact:
98
+
99
+ | The report cut | Ask this instead |
100
+ |---|---|
101
+ | `…truncated at N cells` | `--json`, or `getValues()`, or `--out data.csv` |
102
+ | `…truncated at N of M regions` | `getRegions()` and loop them in the run |
103
+ | `…more regions listed but not profiled` | the sheet report, or `getStats()` on the one you want |
104
+ | `…truncated at N of M tokens` | `getTokens()` and search it |
105
+ | `…N branches not shown` | `getPrecedents()` / `getDependents()` — the whole reach, flat (the heading already counts it) |
106
+
107
+ Same for wanting *less*: `--md.features` names the sections you want, which beats capping a count
108
+ you would then have to reason about. A workbook report without the region firehose is a narrower
109
+ question too — `wb.getWorksheets()`, `wb.getNames()`, `wb.getStats()` each answer one part of it
110
+ outright.
111
+
112
+ On MCP the same options are the `run` tool's `md` argument (`{ features: "fill,borders" }`).
113
+
114
+ `-- --region EU report.csv` reaches the run as `args.region === 'EU'` (named flags are also under
115
+ `args.kv`) and `args._ === ['report.csv']`, with the untouched tail in `args.raw`. Reading
116
+ `args.region` is the form that ports unchanged to MCP, where `args` is the caller's object.
117
+
118
+ The root `SKILL.md` shows the basic forms; these are the ones it doesn't:
119
+
120
+ ```bash
121
+ sheetxl book.xlsx --out book.sxl # convert format (no code)
122
+ sheetxl -f normalize.ts -f validate.ts raw.xlsx --out out.xlsx # pipeline
123
+ sheetxl -e "wb.getWorksheet().getRange('A1:C9').getValues()" \
124
+ data.csv --in.csv.delimiter=";" # format options
125
+ sheetxl book.xlsx --save <<'EOF' # stdin: multi-line code
126
+ const sheet = wb.getWorksheet();
127
+ sheet.getRange('B2').setValue('42%');
128
+ sheet.getRange('B3').setValue('=SUM(B1:B2)');
129
+ EOF
130
+ ```
131
+
132
+ Formats (inferred from extension): `.xlsx`, `.sxl` (native — smaller, faster),
133
+ `.csv` (configurable delimiter), `.json`.
134
+
135
+ ## compile — typecheck without running
136
+
137
+ ```
138
+ sheetxl compile <files…> [--out <path>] [--json] [--quiet]
139
+ ```
140
+
141
+ Compiles and typechecks without executing anything. Diagnostics are positioned,
142
+ so they point at the source line; the exit code is non-zero when there are
143
+ errors, which makes it a usable CI gate.
144
+
145
+ ```bash
146
+ sheetxl compile audit.ts # typecheck one script
147
+ sheetxl compile src/*.ts # or a set
148
+ sheetxl compile audit.ts --out dist/audit.sxlm # also emit the compiled module
149
+ ```
150
+
151
+ Reach for `compile` when there is no workbook in play — a CI gate, or a check on
152
+ a script a human will run later. **You do not need it before executing code**: a
153
+ run that fails to compile returns the same positioned diagnostics, so the run
154
+ *is* the typecheck. Likewise `-f` is not a way to run code you just wrote — that
155
+ goes through `-e` or stdin; what a file is for is `scripting.md`.
156
+
157
+ ## Large workbooks — the CLI is stateless, so parsing repeats
158
+
159
+ Every invocation parses the workbook from scratch. A 50 MB workbook that opens in a
160
+ few seconds costs those seconds *again* on the next call, so a ten-call
161
+ explore-then-edit loop pays them ten times. Three fixes:
162
+
163
+ **Move the iteration inside one run.** A loop that would be N invocations is one
164
+ script and one parse. This is where `log` earns its keep — report per item as you
165
+ go, return the summary:
166
+
167
+ ```bash
168
+ sheetxl -f audit.ts big.xlsx # log() per finding, return the tally
169
+ ```
170
+
171
+ **Convert once, then work on `.sxl`.** The native format is 50–500x smaller and
172
+ significantly faster to load, lossless both ways — so pay the xlsx parse a single
173
+ time and export at the end:
174
+
175
+ ```bash
176
+ sheetxl big.xlsx --out scratch.sxl # pay xlsx once
177
+ sheetxl -e "wb.getWorksheet('Assumptions').getRegions()" scratch.sxl # …fast from here
178
+ sheetxl -f fix.ts scratch.sxl --out out.xlsx # deliver xlsx
179
+ ```
180
+
181
+ **Or use an MCP session**, where the engine stays warm across calls and forking,
182
+ undo and restore are in-memory operations rather than file rewrites
183
+ (`sessions.md`). For a large workbook and a long edit–verify loop, this is the
184
+ right answer.
185
+
186
+ ## Structured questions are one-liners
187
+
188
+ There is no query command, because every result renders: name the subject and its
189
+ report comes back. Which subject answers which question is `reading.md`; the
190
+ order to take them in is the root `SKILL.md`. On a terminal that looks like:
191
+
192
+ ```bash
193
+ sheetxl -e "wb" book.xlsx # the workbook report
194
+ sheetxl -e "wb.getWorksheet('Sheet1').getRegions('formula')" book.xlsx # the formula blocks
195
+ sheetxl -e "wb.getWorksheet('Sheet1').getRegions('anomalies')" book.xlsx # what breaks a pattern, ranked
196
+ sheetxl -e "wb.getAnomalies({ focus: 'unitMismatch', limit: 25 })" book.xlsx # ordered for one kind of defect, every sheet
197
+ sheetxl -e "wb.getRange('B2:B847').getStats()" book.xlsx # aggregates + typed counts
198
+ sheetxl -e "wb.getCell('WACC!H2')" book.xlsx # one cell, every facet
199
+ sheetxl -e "wb.createFormula('=NPV(0.08,B2:B9)')" # a formula, unwritten
200
+ ```
201
+
202
+ A script's own plain objects render too — `sheets.map(s => ({ name: …, rows: … }))`
203
+ comes back as a table — so a probe needs no formatting code. `--json` emits the
204
+ same result as structured JSON, for piping to `jq` and friends.
205
+
206
+ ## grep
207
+
208
+ ```
209
+ sheetxl grep <pattern> [file]
210
+ ```
211
+
212
+ The pattern is a **regex by default** (JS syntax); `-F` makes it literal.
213
+ Excel-style `?`/`*` wildcards are not supported. Matches are per-cell, in
214
+ reading order, each tagged with the layer it matched; truncation is always
215
+ reported.
216
+
217
+ Text that is in no cell is searched too, by default: comments ride their cell;
218
+ a sheet's shapes and charts follow its cells, addressed by the range they are
219
+ anchored over; defined names follow every sheet, addressed by the name.
220
+
221
+ ```
222
+ grep "Fund Size" · workbook · fields display,formula,comment,shape,chart,name · 1 cell · 2 objects in 1 of 3 sheets
223
+ Summary!B4 display Fund Size
224
+ Summary!F2:H6 shape Fund Size is committed capital, not NAV.
225
+ Summary!J4:P20 chart Fund Size by Vintage
226
+ ```
227
+
228
+ ```
229
+ --fields <list> layers to search: display (as shown, format applied),
230
+ value (the stored scalar, what getValue() returns — 0.4
231
+ behind 40%, dates as serials; suppressed per cell when
232
+ identical to display),
233
+ formula (leading = restored), hyperlink (the target),
234
+ numberFormat (the format code, e.g. "0.00%"),
235
+ comment (comments, notes, replies), shape (text on a shape,
236
+ alt text), chart (title, axis titles, series names written
237
+ into the chart, alt text), name (defined names and tables:
238
+ the name, what it refers to, its comment)
239
+ [default: display,formula,comment,shape,chart,name]
240
+ -F, --fixed-strings literal string, not a regex
241
+ -i, --ignore-case case-insensitive (case-sensitive by default, like rg)
242
+ -w, --word match on word boundaries (text edges count as edges)
243
+ -v, --invert cells and objects where no requested field matched
244
+ --scope <scope> a sheet name (globs allowed: "Q*"), Sheet1!A1:D9, or a bare
245
+ range (applied to every sheet) [default: every used range].
246
+ A range narrows shapes and charts to those anchored over it;
247
+ a name is reached by the sheet it is scoped to or the cells
248
+ it designates
249
+ --hidden search hidden rows/columns/sheets, shapes and names (excluded
250
+ by default; naming a hidden sheet in --scope always searches it)
251
+ -C, --context [mode] annotate + group matches by their enclosing block:
252
+ contentful (bare -C) | table — not a ±N line count
253
+ -m, --max-count <n> stop after n matches, cells and objects together
254
+ [default: 200; 0 = unlimited]
255
+ --output <mode> content | addresses | count (per sheet) | sheets
256
+ [default: content]
257
+ ```
258
+
259
+ Error tokens are display text, so they grep directly: `sheetxl grep "#REF!" book.xlsx`.
260
+ "Which cells are percentages" is a format question, not a text question:
261
+ `sheetxl grep "%" --fields numberFormat book.xlsx`.
262
+
263
+ ## Interactive sessions
264
+
265
+ No code means an interactive session — there is no `repl` verb either. `sheetxl`
266
+ opens one on a blank workbook; `sheetxl <file.xlsx>` preloads the file into `wb`.
267
+ Use `-i` to run code first and stay (`sheetxl -i -f fixtures.ts book.xlsx`).
268
+
269
+ Useful dot commands: `.help`, `.api` (the API help screen), `.md [expr]`
270
+ (render a result as markdown), `.info`, `.skills`, `.write <file>` (persist —
271
+ workbook mode only), `.exit`.
272
+
273
+ Every read command is also a dot command, generated from the same descriptors —
274
+ `.grep <pattern> [--flag …]`, with the session's workbook implied. Each is a
275
+ context **function** too (`grep('shipped', { ignoreCase: true })`), which returns
276
+ the data rather than the rendered text, so it composes with everything else at
277
+ the prompt: `(await grep('TODO')).cellCount`.
278
+
279
+ Two session-only globals: `read('<file-or-url>')` loads a workbook (paths resolve
280
+ against the shell directory) and `write(wb [, target])` persists one — bare
281
+ promises are auto-awaited, so neither needs `await`. They exist only in the
282
+ interactive session; a one-shot run receives `wb` and persists via `--save`.
283
+
284
+ ## Composition
285
+
286
+ Everything is a normal process: exit codes, stdout, stdin. Chain with shell
287
+ pipes, run in CI, script with `npx -y sheetxl …` for zero-install environments.
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: embedding
3
+ description: "Building an application with SheetXL — embedding the engine or UI, using @sheetxl/sdk as a library: packages, imports, entry setup, file IO in code, constructing workbooks. Use when writing the user's application code, or a standalone program outside `run`. Triggers on: embed, application, build an app, @sheetxl/sdk, @sheetxl/io, import, WorkbookIO, IOPlugin, new Workbook, library, Studio."
4
+ ---
5
+
6
+ # Embedding SheetXL — Building an App on the SDK
7
+
8
+ > Part of the SheetXL skill suite. See the root `SKILL.md` for routing.
9
+
10
+ This is ordinary software development in the user's repo — no agent modes, no
11
+ sessions, no run context. Import normally and follow the app's conventions.
12
+
13
+ It is also the path for a **standalone program** when the run context cannot
14
+ express a task (e.g. operating on two workbooks at once) — same imports, same
15
+ setup, just your own small program instead of `run`.
16
+
17
+ ## Packages
18
+
19
+ | Package | Purpose |
20
+ |---|---|
21
+ | `@sheetxl/sdk` | Core engine: workbook, sheets, ranges, cells, formulas |
22
+ | `@sheetxl/io` | Format plugins — register once at app entry |
23
+ | `@sheetxl/primitives` | The complete (and only) import surface for formula/UDF authoring |
24
+ | `sheetxl` | The CLI: run, grep, info, setup, MCP |
25
+
26
+ ## Entry setup
27
+
28
+ ```typescript
29
+ import { WorkbookIO } from '@sheetxl/sdk';
30
+ import { IOPlugin } from '@sheetxl/io';
31
+
32
+ WorkbookIO.install(IOPlugin); // once, before any file read/write
33
+ ```
34
+
35
+ ## Files in code
36
+
37
+ `IOPlugin` registers the default supported formats (the table below). Format is
38
+ inferred from the file extension; options go in the third argument:
39
+
40
+ ```typescript
41
+ const wb = await WorkbookIO.read('data.xlsx');
42
+ const csv = await WorkbookIO.read({ source: 'data.csv' }, { delimiter: ';' });
43
+
44
+ await WorkbookIO.writeFile('output.sxl', wb); // recalcs pending formulas first
45
+ await WorkbookIO.writeFile('out.csv', wb, { delimiter: '\t' });
46
+ ```
47
+
48
+ | Extension | Format | Notes |
49
+ |---|---|---|
50
+ | `.xlsx` | Excel Open XML | Full read/write, Excel compatible |
51
+ | `.sxl` | SXL (native) | 50–500x smaller, significantly faster, lossless round-trip |
52
+ | `.csv` | CSV | Configurable delimiter |
53
+ | `.json` | JSON | SheetXL array format |
54
+
55
+ The format trade-off (`.sxl` for working copies, `.xlsx` when Excel opens the
56
+ file) is the root `SKILL.md`; it reads the same from application code.
57
+
58
+ The shipped type definitions are the authoritative API surface —
59
+ `node_modules/@sheetxl/sdk/types/index.d.ts`.
60
+
61
+ ## Constructing a workbook
62
+
63
+ ```typescript
64
+ import { Workbook } from '@sheetxl/sdk';
65
+
66
+ const wb = new Workbook();
67
+ const sheet = wb.getWorksheet();
68
+ ```
69
+
70
+ ## Embedding the UI
71
+
72
+ Studio — the production React UI with full Excel shortcuts and visual
73
+ fidelity — embeds alongside the engine. See https://www.sheetxl.com/docs for
74
+ components and integration guides.