0
# CLI Interface
1
2
Command-line interface for sitemap generation, validation, and parsing. The sitemap CLI provides a convenient way to work with sitemaps from the command line without writing code.
3
4
## Installation
5
6
The CLI is automatically available when you install the sitemap package:
7
8
```bash
9
npm install -g sitemap
10
```
11
12
Or use with npx without global installation:
13
14
```bash
15
npx sitemap [options] [file]
16
```
17
18
## Basic Usage
19
20
### Generate Sitemap from URL List
21
22
The most common use case is generating a sitemap from a list of URLs:
23
24
```bash
25
# From file
26
npx sitemap urls.txt > sitemap.xml
27
28
# From stdin
29
echo -e "/page1\n/page2\n/page3" | npx sitemap > sitemap.xml
30
31
# With hostname
32
echo -e "/page1\n/page2" | npx sitemap --prepend "https://example.com" > sitemap.xml
33
```
34
35
### Validate Existing Sitemap
36
37
Validate an existing sitemap against the XML schema:
38
39
```bash
40
# Validate sitemap file
41
npx sitemap --validate sitemap.xml
42
43
# Validate from URL
44
curl -s https://example.com/sitemap.xml | npx sitemap --validate
45
```
46
47
### Parse Sitemap to JSON
48
49
Convert XML sitemap to JSON format for analysis:
50
51
```bash
52
# Parse to JSON array
53
npx sitemap --parse sitemap.xml > sitemap.json
54
55
# Parse to line-separated JSON (one object per line)
56
npx sitemap --parse --single-line-json sitemap.xml > sitemap.jsonl
57
```
58
59
## Command Line Options
60
61
```bash
62
npx sitemap [options] [input-file]
63
```
64
65
### Options
66
67
```typescript { .api }
68
interface CLIOptions {
69
/** Show help information */
70
'--help': boolean;
71
'-h': boolean; // alias for --help
72
73
/** Show version information */
74
'--version': boolean;
75
76
/** Validate XML sitemap against schema (requires xmllint) */
77
'--validate': boolean;
78
79
/** Parse existing sitemap to JSON format */
80
'--parse': boolean;
81
82
/** Output JSON as single-line format (one object per line) */
83
'--single-line-json': boolean;
84
85
/** Generate sitemap index with multiple sitemap files */
86
'--index': boolean;
87
88
/** Base URL for sitemap index */
89
'--index-base-url': string;
90
91
/** Maximum URLs per sitemap file (default: 50000) */
92
'--limit': number;
93
94
/** Prepend hostname to relative URLs */
95
'--prepend': string;
96
97
/** Compress output with gzip */
98
'--gzip': boolean;
99
}
100
```
101
102
## Advanced Usage Examples
103
104
### Generate Large Sitemap with Index
105
106
For websites with more than 50,000 URLs, generate multiple sitemap files with an index:
107
108
```bash
109
# Create sitemap index with max 10,000 URLs per file
110
npx sitemap --index --limit 10000 --index-base-url "https://example.com" large-urls.txt
111
112
# This creates:
113
# - sitemap-0.xml
114
# - sitemap-1.xml
115
# - sitemap-2.xml
116
# - sitemap-index.xml
117
```
118
119
### Process JSON Input
120
121
Handle JSON input with sitemap metadata:
122
123
```bash
124
# Create JSON file with sitemap items
125
cat > urls.json << 'EOF'
126
{"url": "/page1", "changefreq": "daily", "priority": 0.8}
127
{"url": "/page2", "changefreq": "weekly", "priority": 0.6}
128
{"url": "/page3", "priority": 0.4}
129
EOF
130
131
# Generate sitemap from JSON
132
npx sitemap --prepend "https://example.com" urls.json > sitemap.xml
133
```
134
135
### Compressed Output
136
137
Generate compressed sitemaps to save bandwidth:
138
139
```bash
140
# Generate compressed sitemap
141
npx sitemap --gzip --prepend "https://example.com" urls.txt > sitemap.xml.gz
142
143
# Generate compressed index and sitemaps
144
npx sitemap --index --gzip --limit 25000 \
145
--index-base-url "https://example.com" \
146
--prepend "https://example.com" \
147
large-urls.txt
148
```
149
150
### Validation Workflows
151
152
```bash
153
# Validate multiple sitemaps
154
for sitemap in sitemap-*.xml; do
155
echo "Validating $sitemap..."
156
npx sitemap --validate "$sitemap" || echo "❌ $sitemap is invalid"
157
done
158
159
# Parse and validate pipeline
160
npx sitemap --parse sitemap.xml | \
161
jq '.[] | select(.priority > 0.5)' | \
162
npx sitemap --prepend "https://example.com" > high-priority.xml
163
```
164
165
## Input Formats
166
167
### Plain Text URLs
168
169
```
170
/page1
171
/page2
172
/about
173
/contact
174
```
175
176
### JSON Lines Format
177
178
```json
179
{"url": "/page1", "changefreq": "daily", "priority": 0.8}
180
{"url": "/page2", "changefreq": "weekly", "priority": 0.6}
181
{"url": "/page3", "lastmod": "2023-01-15"}
182
```
183
184
### JSON Array Format
185
186
```json
187
[
188
{"url": "/page1", "changefreq": "daily", "priority": 0.8},
189
{"url": "/page2", "changefreq": "weekly", "priority": 0.6},
190
{"url": "/page3", "lastmod": "2023-01-15"}
191
]
192
```
193
194
## Output Examples
195
196
### Standard Sitemap XML
197
198
```xml
199
<?xml version="1.0" encoding="UTF-8"?>
200
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
201
<url>
202
<loc>https://example.com/page1</loc>
203
<changefreq>daily</changefreq>
204
<priority>0.8</priority>
205
</url>
206
<url>
207
<loc>https://example.com/page2</loc>
208
<changefreq>weekly</changefreq>
209
<priority>0.6</priority>
210
</url>
211
</urlset>
212
```
213
214
### Sitemap Index XML
215
216
```xml
217
<?xml version="1.0" encoding="UTF-8"?>
218
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
219
<sitemap>
220
<loc>https://example.com/sitemap-0.xml</loc>
221
<lastmod>2023-01-15T10:30:00.000Z</lastmod>
222
</sitemap>
223
<sitemap>
224
<loc>https://example.com/sitemap-1.xml</loc>
225
<lastmod>2023-01-15T10:30:00.000Z</lastmod>
226
</sitemap>
227
</sitemapindex>
228
```
229
230
### Parsed JSON Output
231
232
```json
233
[
234
{
235
"url": "https://example.com/page1",
236
"changefreq": "daily",
237
"priority": 0.8,
238
"img": [],
239
"video": [],
240
"links": []
241
},
242
{
243
"url": "https://example.com/page2",
244
"changefreq": "weekly",
245
"priority": 0.6,
246
"img": [],
247
"video": [],
248
"links": []
249
}
250
]
251
```
252
253
## Error Handling
254
255
The CLI provides detailed error messages for common issues:
256
257
```bash
258
# Missing URL error
259
echo '{"priority": 0.8}' | npx sitemap
260
# Error: URL is required for sitemap items
261
262
# Invalid priority error
263
echo '{"url": "/test", "priority": 2.0}' | npx sitemap
264
# Error: Priority must be between 0.0 and 1.0
265
266
# Validation error
267
npx sitemap --validate invalid-sitemap.xml
268
# Error: XML validation failed: element url: Schemas validity error
269
```
270
271
## Integration Examples
272
273
### CI/CD Pipeline
274
275
```bash
276
#!/bin/bash
277
# generate-sitemap.sh
278
279
# Generate sitemap from database export
280
mysql -u user -p database -e "SELECT CONCAT('/product/', id) FROM products" \
281
--skip-column-names --batch | \
282
npx sitemap --prepend "https://shop.example.com" \
283
--gzip > sitemap.xml.gz
284
285
# Validate the generated sitemap
286
if npx sitemap --validate sitemap.xml.gz; then
287
echo "✅ Sitemap generated and validated successfully"
288
# Upload to CDN or web server
289
aws s3 cp sitemap.xml.gz s3://my-bucket/sitemap.xml.gz
290
else
291
echo "❌ Sitemap validation failed"
292
exit 1
293
fi
294
```
295
296
### Cron Job
297
298
```bash
299
# Daily sitemap generation
300
0 2 * * * /usr/local/bin/generate-sitemap.sh >> /var/log/sitemap.log 2>&1
301
```
302
303
### Docker Usage
304
305
```dockerfile
306
FROM node:18-alpine
307
RUN npm install -g sitemap
308
COPY urls.txt /app/
309
WORKDIR /app
310
CMD ["npx", "sitemap", "--prepend", "https://example.com", "urls.txt"]
311
```
312
313
## Requirements
314
315
- Node.js 14.0.0 or higher
316
- NPM 6.0.0 or higher
317
- For `--validate` option: xmllint (part of libxml2-utils package)
318
319
### Installing xmllint
320
321
```bash
322
# Ubuntu/Debian
323
sudo apt-get install libxml2-utils
324
325
# macOS with Homebrew
326
brew install libxml2
327
328
# Alpine Linux (Docker)
329
apk add --no-cache libxml2-utils
330
```