You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>As an alternative to typing commands on the command line, you can put them in a plain-text command file and run them with the mapshaper CLI.</p>
122
+
<p>Command files offer a few conveniences over a shell script or Makefile:</p>
123
+
<ul>
124
+
<li>Hash-delimited (<code>#</code>) comments, both on their own line and at the end of a line.</li>
125
+
<li>No need to escape <code>*</code> or other shell metacharacters; commands aren't passed through the shell.</li>
126
+
<li>Trailing-backslash line continuations are accepted but not required — lines that don't begin with <code>-</code> are joined onto the previous command.</li>
127
+
<li>Variable interpolation using <code>{{VAR}}</code> placeholders. See <ahref="#variables">variables</a> below.</li>
128
+
</ul>
129
+
<p>(Support for running command files in the mapshaper web UI is planned for a future release.)</p>
130
+
<h3id="file-format">File format</h3>
131
+
<p>A mapshaper command file is a <code>.txt</code> file whose first non-blank, non-comment line starts with <code>mapshaper</code>.</p>
132
+
<pre><code>mapshaper
133
+
-i provinces.shp
134
+
# Use Douglas Peucker simplification
135
+
-simplify dp 20%
136
+
-o precision=0.00001 output.geojson
137
+
</code></pre>
138
+
<p>If you write the command file using shell-compatible syntax — trailing <code>\</code> for line continuations and no <code>#</code> comments — it can also be pasted directly onto a bash command line, where the leading <code>mapshaper</code> word invokes the CLI. To make the above example shell compatible, you could write:</p>
139
+
<pre><code>mapshaper \
140
+
-i provinces.shp \
141
+
-simplify dp 20% \
142
+
-o precision=0.00001 output.geojson
143
+
</code></pre>
144
+
<h3id="running-a-command-file">Running a command file</h3>
145
+
<p>The command for running a command file is <ahref="#-run"><code>-run</code></a>:</p>
<p>Command files and command lines may contain <code>{{VAR}}</code> placeholders, which are substituted just before each command runs. Two forms are recognized:</p>
151
+
<ul>
152
+
<li><code>{{VAR}}</code> — substituted with the value of <code>VAR</code>.</li>
153
+
<li><code>{{env.NAME}}</code> — substituted with the value of the <code>NAME</code> environment variable.</li>
154
+
</ul>
155
+
<p>This syntax allows you to interpolate all or part of a command option. For example, <code>-simplify {{SIMPLIFY_METHOD}} resolution={{SIMPLIFY_RESOLUTION}}</code>.</p>
156
+
<p>Variables can be set in several ways:</p>
157
+
<ul>
158
+
<li>The <ahref="#-vars"><code>-vars</code></a> command sets one or more variables, always overwriting any previous value.</li>
159
+
<li>The <ahref="#-defaults"><code>-defaults</code></a> command set only those values that do not already exist.</li>
160
+
<li>Assignments in <code>-calc</code> and <code>-define</code> expressions create new variables.</li>
161
+
<li>Assigning a property to the <code>global</code> object in an <code>-each</code> expression creates a new variable.</li>
162
+
</ul>
163
+
<p><code>-vars</code> and <code>-defaults</code> write to a templating-scope store; the other commands write to an expression-scope store (<code>global</code>). <code>{{X}}</code> substitution checks the templating scope first and falls back to the expression scope, so values from any of the four mechanisms above are reachable. Bare names in JS expressions only see the expression scope — a name set by <code>-vars</code> is <em>not</em> readable by bare name from inside <code>-each</code>, <code>-filter</code>, etc. See <ahref="/docs/guides/expressions.html#sharing-state-across-commands">JavaScript expressions</a> for the full story.</p>
@@ -125,7 +183,7 @@ <h2 id="working-with-layers">Working with layers</h2>
125
183
</main>
126
184
127
185
<asideclass="docs-toc">
128
-
<divclass="docs-toc-title">On this page</div><ul><liclass="lvl-2"><ahref="#install">Install</a></li><liclass="lvl-2"><ahref="#anatomy-of-a-mapshaper-command">Anatomy of a Mapshaper command</a></li><liclass="lvl-2"><ahref="#some-examples">Some examples</a></li><liclass="lvl-3"><ahref="#get-help">Get help</a></li><liclass="lvl-3"><ahref="#chain-commands">Chain commands</a></li><liclass="lvl-2"><ahref="#working-with-layers">Working with layers</a></li></ul>
186
+
<divclass="docs-toc-title">On this page</div><ul><liclass="lvl-2"><ahref="#install">Install</a></li><liclass="lvl-2"><ahref="#anatomy-of-a-mapshaper-command">Anatomy of a Mapshaper command</a></li><liclass="lvl-2"><ahref="#some-examples">Some examples</a></li><liclass="lvl-3"><ahref="#get-help">Get help</a></li><liclass="lvl-3"><ahref="#chain-commands">Chain commands</a></li><liclass="lvl-2"><ahref="#working-with-layers">Working with layers</a></li><liclass="lvl-2"><ahref="#command-files">Command files</a></li><liclass="lvl-3"><ahref="#file-format">File format</a></li><liclass="lvl-3"><ahref="#running-a-command-file">Running a command file</a></li><liclass="lvl-2"><ahref="#variable-interpolation">Variable interpolation</a></li></ul>
Copy file name to clipboardExpand all lines: docs/essentials/command-line.html.md
+82Lines changed: 82 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -110,3 +110,85 @@ mapshaper usa.topojson \
110
110
-filter 'STATE == "HI"' target=states \
111
111
-o out/hawaii.geojson
112
112
```
113
+
114
+
## Command files
115
+
116
+
As an alternative to typing commands on the command line, you can put them in a plain-text command file and run them with the mapshaper CLI.
117
+
118
+
Command files offer a few conveniences over a shell script or Makefile:
119
+
120
+
- Hash-delimited (`#`) comments, both on their own line and at the end of a line.
121
+
- No need to escape `*` or other shell metacharacters; commands aren't passed through the shell.
122
+
- Trailing-backslash line continuations are accepted but not required — lines that don't begin with `-` are joined onto the previous command.
123
+
- Variable interpolation using `{{VAR}}` placeholders. See [variables](#variables) below.
124
+
125
+
(Support for running command files in the mapshaper web UI is planned for a future release.)
126
+
127
+
### File format
128
+
129
+
A mapshaper command file is a `.txt` file whose first non-blank, non-comment line starts with `mapshaper`.
130
+
131
+
```
132
+
mapshaper
133
+
-i provinces.shp
134
+
# Use Douglas Peucker simplification
135
+
-simplify dp 20%
136
+
-o precision=0.00001 output.geojson
137
+
```
138
+
139
+
If you write the command file using shell-compatible syntax — trailing `\` for line continuations and no `#` comments — it can also be pasted directly onto a bash command line, where the leading `mapshaper` word invokes the CLI. To make the above example shell compatible, you could write:
140
+
141
+
```
142
+
mapshaper \
143
+
-i provinces.shp \
144
+
-simplify dp 20% \
145
+
-o precision=0.00001 output.geojson
146
+
```
147
+
148
+
### Running a command file
149
+
150
+
The command for running a command file is [`-run`](#-run):
151
+
152
+
```bash
153
+
mapshaper -run build.txt
154
+
```
155
+
156
+
`mapshaper commands.txt` is a shortcut for `mapshaper -run commands.txt`.
157
+
158
+
## Variable interpolation
159
+
160
+
Command files and command lines may contain `{{VAR}}` placeholders, which are substituted just before each command runs. Two forms are recognized:
161
+
162
+
-`{{VAR}}`— substituted with the value of `VAR`.
163
+
-`{{env.NAME}}`— substituted with the value of the `NAME` environment variable.
164
+
165
+
This syntax allows you to interpolate all or part of a command option. For example, `-simplify {{SIMPLIFY_METHOD}} resolution={{SIMPLIFY_RESOLUTION}}`.
166
+
167
+
Variables can be set in several ways:
168
+
- The [`-vars`](#-vars) command sets one or more variables, always overwriting any previous value.
169
+
- The [`-defaults`](#-defaults) command set only those values that do not already exist.
170
+
- Assignments in `-calc` and `-define` expressions create new variables.
171
+
- Assigning a property to the `global` object in an `-each` expression creates a new variable.
172
+
173
+
`-vars` and `-defaults` write to a templating-scope store; the other commands write to an expression-scope store (`global`). `{{X}}` substitution checks the templating scope first and falls back to the expression scope, so values from any of the four mechanisms above are reachable. Bare names in JS expressions only see the expression scope — a name set by `-vars` is *not* readable by bare name from inside `-each`, `-filter`, etc. See [JavaScript expressions](/docs/guides/expressions.html.md#sharing-state-across-commands) for the full story.
<h2id="optional-ai-assistant">Optional AI assistant</h2>
150
-
<p>Some Mapshaper installations may enable an optional AI assistant by serving an <code>ai-config.js</code> file alongside the web app. If the file is missing or disabled, no assistant UI is shown.</p>
151
-
<p>When enabled, the assistant can receive the same runtime context shown by the console's <code>context</code> command: layer names, field names/types, feature counts, CRS, recent commands and recent messages. It does not include geometry or full attribute records.</p>
152
-
<p>Development builds can use a mock assistant or direct provider calls from <code>localhost</code>. Production deployments should use a proxy endpoint so provider secrets, rate limits and logging policy are not exposed in the browser.</p>
153
-
<p>An <code>ai-config.js</code> file can also point the assistant at static documentation, such as <code>llms-full.txt</code>, for providers or proxies that support prompt caching:</p>
<p>For local testing without a proxy, <code>mode: "direct"</code> supports OpenAI-compatible Responses requests and Anthropic Messages requests. Anthropic direct mode sends static context as cacheable system content when <code>provider: "anthropic"</code> is configured. Direct mode should only be used with disposable development keys on <code>localhost</code>.</p>
164
149
<h2id="browser-support">Browser support</h2>
165
150
<p>When importing very large files (hundreds of megabytes), the web app may run out of memory and crash. Firefox used to be better than Chrome at handling large files, but Chrome seems to have improved recently. If the web app crashes, try the <ahref="/docs/essentials/command-line.html"><code>mapshaper-xl</code> command-line tool</a>, which can allocate a large amount of memory.</p>
166
151
<h2id="privacy">Privacy</h2>
@@ -173,7 +158,7 @@ <h2 id="privacy">Privacy</h2>
173
158
</main>
174
159
175
160
<asideclass="docs-toc">
176
-
<divclass="docs-toc-title">On this page</div><ul><liclass="lvl-2"><ahref="#loading-data">Loading data</a></li><liclass="lvl-3"><ahref="#tips-for-importing-shapefiles">Tips for importing Shapefiles</a></li><liclass="lvl-2"><ahref="#the-console">The console</a></li><liclass="lvl-3"><ahref="#keyboard">Keyboard</a></li><liclass="lvl-3"><ahref="#syntax">Syntax</a></li><liclass="lvl-3"><ahref="#using-cli-examples-in-the-web-console">Using CLI examples in the web console</a></li><liclass="lvl-3"><ahref="#magic-words-at-the-prompt">Magic words at the prompt</a></li><liclass="lvl-3"><ahref="#discovering-commands">Discovering commands</a></li><liclass="lvl-2"><ahref="#the-map">The map</a></li><liclass="lvl-3"><ahref="#right-click-menu">Right-click menu</a></li><liclass="lvl-3"><ahref="#layer-navigation">Layer navigation</a></li><liclass="lvl-2"><ahref="#display-options">Display options</a></li><liclass="lvl-2"><ahref="#snapshots-and-session-history">Snapshots and session history</a></li><liclass="lvl-2"><ahref="#running-the-web-ui-locally">Running the web UI locally</a></li><liclass="lvl-2"><ahref="#optional-ai-assistant">Optional AI assistant</a></li><liclass="lvl-2"><ahref="#browser-support">Browser support</a></li><liclass="lvl-2"><ahref="#privacy">Privacy</a></li></ul>
161
+
<divclass="docs-toc-title">On this page</div><ul><liclass="lvl-2"><ahref="#loading-data">Loading data</a></li><liclass="lvl-3"><ahref="#tips-for-importing-shapefiles">Tips for importing Shapefiles</a></li><liclass="lvl-2"><ahref="#the-console">The console</a></li><liclass="lvl-3"><ahref="#keyboard">Keyboard</a></li><liclass="lvl-3"><ahref="#syntax">Syntax</a></li><liclass="lvl-3"><ahref="#using-cli-examples-in-the-web-console">Using CLI examples in the web console</a></li><liclass="lvl-3"><ahref="#magic-words-at-the-prompt">Magic words at the prompt</a></li><liclass="lvl-3"><ahref="#discovering-commands">Discovering commands</a></li><liclass="lvl-2"><ahref="#the-map">The map</a></li><liclass="lvl-3"><ahref="#right-click-menu">Right-click menu</a></li><liclass="lvl-3"><ahref="#layer-navigation">Layer navigation</a></li><liclass="lvl-2"><ahref="#display-options">Display options</a></li><liclass="lvl-2"><ahref="#snapshots-and-session-history">Snapshots and session history</a></li><liclass="lvl-2"><ahref="#running-the-web-ui-locally">Running the web UI locally</a></li><liclass="lvl-2"><ahref="#browser-support">Browser support</a></li><liclass="lvl-2"><ahref="#privacy">Privacy</a></li></ul>
Copy file name to clipboardExpand all lines: docs/essentials/web-app.html.md
-23Lines changed: 0 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -128,29 +128,6 @@ You can pre-load files by listing them on the command line, which skips the impo
128
128
mapshaper-gui states.shp rivers.shp
129
129
```
130
130
131
-
## Optional AI assistant
132
-
133
-
Some Mapshaper installations may enable an optional AI assistant by serving an `ai-config.js` file alongside the web app. If the file is missing or disabled, no assistant UI is shown.
134
-
135
-
When enabled, the assistant can receive the same runtime context shown by the console's `context` command: layer names, field names/types, feature counts, CRS, recent commands and recent messages. It does not include geometry or full attribute records.
136
-
137
-
Development builds can use a mock assistant or direct provider calls from `localhost`. Production deployments should use a proxy endpoint so provider secrets, rate limits and logging policy are not exposed in the browser.
138
-
139
-
An `ai-config.js` file can also point the assistant at static documentation, such as `llms-full.txt`, for providers or proxies that support prompt caching:
140
-
141
-
```js
142
-
window.mapshaperAI= {
143
-
enabled:true,
144
-
mode:"proxy",
145
-
endpoint:"/api/mapshaper-assist",
146
-
staticContextUrl:"/llms-full.txt",
147
-
cacheControl: {type:"ephemeral"},
148
-
cacheTtl:"1h"
149
-
};
150
-
```
151
-
152
-
For local testing without a proxy, `mode: "direct"` supports OpenAI-compatible Responses requests and Anthropic Messages requests. Anthropic direct mode sends static context as cacheable system content when `provider: "anthropic"` is configured. Direct mode should only be used with disposable development keys on `localhost`.
153
-
154
131
## Browser support
155
132
156
133
When importing very large files (hundreds of megabytes), the web app may run out of memory and crash. Firefox used to be better than Chrome at handling large files, but Chrome seems to have improved recently. If the web app crashes, try the [`mapshaper-xl` command-line tool](/docs/essentials/command-line.html.md), which can allocate a large amount of memory.
Copy file name to clipboardExpand all lines: docs/examples/basics.html
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -220,7 +220,7 @@ <h3 id="run-a-chain-of-commands-from-a-file">Run a chain of commands from a file
220
220
<spanclass="hljs-comment"># or simply:</span>
221
221
mapshaper build.txt
222
222
</code></pre>
223
-
<p>Long pipelines can be kept in a <ahref="/docs/reference.html#command-files">command file</a>. This is a CLI workflow; support for running command files in the web app is planned for a future release.</p>
223
+
<p>Long pipelines can be kept in a <ahref="/docs/essentials/command-line.html#command-files">command file</a>. This is a CLI workflow; support for running command files in the web app is planned for a future release.</p>
224
224
<h3id="parameterize-a-command-file">Parameterize a command file</h3>
Copy file name to clipboardExpand all lines: docs/examples/basics.html.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -324,7 +324,7 @@ mapshaper -run build.txt
324
324
mapshaper build.txt
325
325
```
326
326
327
-
Long pipelines can be kept in a [command file](/docs/reference.html.md#command-files). This is a CLI workflow; support for running command files in the web app is planned for a future release.
327
+
Long pipelines can be kept in a [command file](/docs/essentials/command-line.html.md#command-files). This is a CLI workflow; support for running command files in the web app is planned for a future release.
<p>Each entry in <code>targets</code> exposes useful summary stats from <code>-info</code>: <code>layer_name</code>, <code>feature_count</code>, <code>null_shape_count</code>, <code>null_data_count</code>, <code>bbox</code>, <code>proj4</code>. Reading <code>targets[0].geojson</code> returns the layer as a GeoJSON FeatureCollection; assigning to it replaces the layer with the FeatureCollection you provide.</p>
<p><code>-run</code> accepts either a path to a <ahref="/docs/reference.html#command-files">command file</a> or a string containing one or more curly-brace template expressions. Each <code>{...}</code> is evaluated as a JS expression and substituted into the resulting command string before Mapshaper parses it.</p>
528
+
<p><code>-run</code> accepts either a path to a <ahref="/docs/essentials/command-line.html#command-files">command file</a> or a string containing one or more curly-brace template expressions. Each <code>{...}</code> is evaluated as a JS expression and substituted into the resulting command string before Mapshaper parses it.</p>
529
529
<pre><codeclass="hljs language-bash"><spanclass="hljs-comment"># Project to a transverse Mercator centred on the layer</span>
0 commit comments