Parse command-line arguments with a flag and option spec
List the switches and options your program accepts, and it sorts the command line for you: --tag=stable --tag latest becomes the two tags stable and latest, src.js stays a plain argument and --mystery is reported as unknown. Free in your browser.
- Free
- Runs in your browser
- No sign-up
- Your data stays on your device
Run — free
Runs in your browser. Free, unlimited — your data never leaves this page.
Turn a raw command-line argument array into a predictable object without embedding parser-specific behavior throughout your application. Malformed specifications, duplicate arguments, and options without required values produce clear input errors.
Describe the command-line interface as data
Start with the argument tokens exactly as a runtime supplies them after removing the executable and script names. Then define each accepted argument in the spec. Use flag for a switch whose presence means true, such as <code>--verbose</code>.
Use option when the spelling must be followed by a value, such as <code>--output result.json</code>. Canonical names use lowercase letters, digits, and underscores, making the returned object safe to consume without another renaming pass. Set <code>multiple</code> only when repeating an argument is intentionally part of the interface; repeated values are then returned in encounter order.
Understand token parsing and output
The result separates three concerns: recognized values, positional tokens, and unknown flags. Recognized flags become true under their canonical names, while options store their following token. A long option can also carry its value in the same token, as in <code>--format=json</code>.
Other unrecognized tokens are positional values. A standalone <code>--</code> ends option processing, and every later token is positional even if it begins with a hyphen. This conventional escape makes filenames such as <code>-draft.txt</code> unambiguous.
The parser does not invent defaults or coerce strings into numbers, because those policies belong to the application and can otherwise hide user mistakes. Its output is deterministic and preserves the order of positional and unknown items.
Handle missing values and repeated arguments safely
The same rule applies to an empty attached form such as <code>--output=</code>. This strict behavior prevents a later switch from being silently consumed as data and addresses the most damaging command-line parsing failure directly. A lone hyphen may still be used as an option value, which is useful for programs that treat standard input or standard output as <code>-</code>.
By default, presenting the same recognized argument twice is also an error. Declare <code>multiple: true</code> when repetition is valid, such as multiple include paths or labels; the output will then always contain an array for that canonical name. Unknown flags are merely reported rather than causing failure, so the caller retains control over compatibility and forwarding policy.
What you can do with it
Validate a CLI wrapper
Parse wrapper-specific options while reporting unsupported flags before launching the wrapped process.
FAQ
What does it cost?
The browser version runs the same deterministic parsing logic locally.
Does it support --name=value syntax?
Yes, for long value-taking options. An empty value after the equals sign is an error.
What happens after a standalone double dash?
Option parsing stops and every remaining token is returned as a positional argument.
Can -o and --output fill the same option?
Yes. Declare both spellings under one name and either of them stores its value there, so short and long forms give exactly the same result. Two options sharing a spelling are refused, because the outcome would depend on the order you wrote them.
What happens if an option is missing its value?
Reading stops with a clear error that names the spelling at fault. That happens when the option is the last word, sits right before the double dash or is followed by another flag, so a later switch is never swallowed as data.
Related tools
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, by email and from Telegram — and soon from our app too.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/dev2/cli-arg-parse-spec \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"args":["--verbose","--output=result.json","input.txt"],"spec":[{"name":"verbose","aliases":["--verbose","-v"],"kind":"flag"},{"name":"output","aliases":["--output","-o"],"kind":"option"}]}'const res = await fetch("https://api.kit.forhosting.com/dev2/cli-arg-parse-spec", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"args": [
"--verbose",
"--output=result.json",
"input.txt"
],
"spec": [
{
"name": "verbose",
"aliases": [
"--verbose",
"-v"
],
"kind": "flag"
},
{
"name": "output",
"aliases": [
"--output",
"-o"
],
"kind": "option"
}
]
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/dev2/cli-arg-parse-spec",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"args": [
"--verbose",
"--output=result.json",
"input.txt"
],
"spec": [
{
"name": "verbose",
"aliases": [
"--verbose",
"-v"
],
"kind": "flag"
},
{
"name": "output",
"aliases": [
"--output",
"-o"
],
"kind": "option"
}
]
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev2/cli-arg-parse-spec", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"args":["--verbose","--output=result.json","input.txt"],"spec":[{"name":"verbose","aliases":["--verbose","-v"],"kind":"flag"},{"name":"output","aliases":["--output","-o"],"kind":"option"}]}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"args":["--verbose","--output=result.json","input.txt"],"spec":[{"name":"verbose","aliases":["--verbose","-v"],"kind":"flag"},{"name":"output","aliases":["--output","-o"],"kind":"option"}]}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev2/cli-arg-parse-spec", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"args": [
"--verbose",
"--output=result.json",
"input.txt"
],
"spec": [
{
"name": "verbose",
"aliases": [
"--verbose",
"-v"
],
"kind": "flag"
},
{
"name": "output",
"aliases": [
"--output",
"-o"
],
"kind": "option"
}
]
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "dev2.cli_arg_parse_spec",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |
Technical notes
Provide the tokens and a compact specification that names each boolean flag or value-taking option. The parser resolves aliases to canonical names, preserves positional arguments, identifies unknown flags, supports long options with an equals sign, and stops option parsing after the conventional double-dash marker.
Describe the command-line interface as data
Every entry has a canonical name, one or more aliases, and a kind. Aliases let short and long spellings populate the same canonical property, so <code>-o</code> and <code>--output</code> can both produce <code>output</code>. Alias spellings must begin with one or two hyphens. The parser rejects duplicate canonical names and duplicate aliases because either collision would make the result depend on declaration order.
Understand token parsing and output
An exact token match is required; short-flag bundles such as <code>-abc</code> are not expanded unless that entire spelling appears as an alias. Any unrecognized token beginning with a hyphen is appended to <code>unknown_flags</code>, allowing callers to reject it, display a warning, or forward it deliberately.
Handle missing values and repeated arguments safely
Every entry whose kind is option requires a non-empty value whenever its alias appears. If the alias is the final token, is followed by the end-of-options marker, or is followed by another flag-shaped token, parsing fails with an invalid-input error that names the offending alias.
Integration use cases
Normalize short and long options
Map aliases such as -o and --output to one stable property for simpler application logic.
Build command previews and tests
Convert token arrays into deterministic structured fixtures without executing a command or accessing a shell.
Technical questions
Are unknown flags rejected?
No. They are returned in unknown_flags so the caller can reject, warn about, or forward them.
Does it combine short flags such as -abc?
No. Aliases match whole tokens, so -abc is recognized only if the spec declares that exact alias.