@@ -10,7 +10,7 @@ layer, the facts that are expensive to rediscover.
 - **`Parser`** reads a command line against the tree and returns an immutable `ParseResult`.
   It holds no state.
 - **`HelpRenderer`** draws the help of any node, `render()` into a console and
-  `renderToString()` into a string. Like `Parser`, it takes the node as an argument and keeps
+  `renderToString()` into a string, and `renderError()` a usage error followed by that help. Like `Parser`, it takes the node as an argument and keeps
   nothing between calls.
 - **`Console`** writes to a stream and knows no `Command`. The renderer colors and writes
   through it; `renderToString()` without a console is plain text.
@@ -115,7 +115,7 @@ Consequences worth knowing:
   without losing the reason for the phases.
 - An exception from `normalize()`, a value outside the enum or one a normalizer refused, is
   wrapped into a `ParseException` naming the parameter, with the original as `previous`, so all
-  bad values read alike ("Option --x: expects …"). A `ParseException` passes through untouched and an
+  bad values read alike ("Option `--x`: expects …"). A `ParseException` passes through untouched and an
   `\Error` is not caught at all: a broken normalizer is a bug, not a bad value. The
   `catch (\Exception)` is deliberate, and the `dresscode:ignore` comment beside it must
   stand alone at the end of the line, since text after it is read as rule names.
@@ -129,6 +129,13 @@ Consequences worth knowing:
   `token` the raw part of the line as given (the name without its value, a letter of a bundle
   on its own), null for what is missing; one a normalizer throws itself passes through with the
   default reason `InvalidValue` and no token.
+- **`ParseException` extends `UsageException`**, which a handler throws for what the definition
+  cannot express (inputs that conflict, a value that does not fit the context), so an application
+  catches one class and draws both alike by `renderError()`. The command of either is required.
+- **Messages write code in backticks**, as descriptions do: names, commands and the values given,
+  each through `HelpRenderer::formatCode()`, which also escapes control characters, since a code
+  span does not cross a line, and writes a value holding a backtick in a longer run of them;
+  `formatText()` and `splitCodeSpans()` read it back.
 
 **`standalone`** is answered between phase 1 and phase 2, so the command is already selected:
 if such a flag of the selected path occurred, the other flags are taken as they occurred
@@ -272,8 +279,8 @@ break a line in different places.
 The help colors only through its own **roles**, which the private `HelpRenderer::Theme` maps to
 the colors of `Console::color()`; `Console` knows no roles. Roles are chosen by conditions, so a
 role missing from the map shows only when that branch is drawn in color, which the colored
-snapshot `tests/snapshots/fluent.ansi.txt` does for all of them but `code`, drawn in color by
-`tests/HelpRenderer.phpt`.
+snapshot `tests/snapshots/fluent.ansi.txt` does for all of them but `code` and `error`, drawn in
+color by `tests/HelpRenderer.phpt`.
 
 ## Console: one stream, two questions about it
 
 
@@ -225,7 +225,7 @@ $command->addOption('--count', normalizer: Normalizers::int(min: 1));
 // --count 0    → throws "Option --count: expects at least 1, 0 given."
 ```
 
-It runs only on values that really come from the command line: not on the default value, and not on the `true` of an option used without its optional value. A normalizer reports a bad value by throwing an exception. The parser turns it into a `ParseException` naming the parameter, so the user reads `Option --count: expects an integer, 'abc' given.` instead of a stack trace. An `\Error` is not caught, because a broken normalizer is a bug, not a bad value.
+It runs only on values that really come from the command line: not on the default value, and not on the `true` of an option used without its optional value. A normalizer reports a bad value by throwing an exception. The parser turns it into a `ParseException` naming the parameter, so the user reads ``Option `--count`: expects an integer, `abc` given.`` instead of a stack trace. An `\Error` is not caught, because a broken normalizer is a bug, not a bad value.
 
 `realPath()` resolves the value to an absolute path and refuses a path that does not exist, and an empty one:
 
@@ -473,37 +473,48 @@ When a standalone flag is used, the parser returns it as `true`, the other flags
 Error Handling
 ==============
 
-The parser throws `Nette\CommandLine\ParseException` for invalid user input. Its `command` property is the command in which the input went wrong, so you can show the right help:
+The parser throws `Nette\CommandLine\ParseException` for invalid user input. It is a `UsageException`, which your handler throws for a mistake the definition cannot express, such as two options that cannot be combined. Its `command` is the command in which the input went wrong, and `renderError()` prints the message followed by the help of that command:
 
 ```php
-use Nette\CommandLine\ParseException;
+use Nette\CommandLine\UsageException;
 
 try {
 	$args = (new Parser)->parse($cli);
-} catch (ParseException $e) {
-	$stderr = new Console(STDERR);
-	$stderr->writeLine("Error: {$e->getMessage()}");
-	$stderr->writeLine();
-	(new HelpRenderer($stderr))->render($e->command);
+	exit($args->run());
+} catch (UsageException $e) {
+	(new HelpRenderer(new Console(STDERR)))->renderError($e);
 	exit(2);
 }
 ```
 
-Its `reason` tells what was wrong, as a case of the `ParseFailure` enum, such as `ParseFailure::UnknownOption` or `ParseFailure::MissingArgument`, `parameter` is the parameter the error concerns, when there is one, and `token` the part of the command line it is about, as given: the name of an option as written, without its value, a command, the first unexpected argument or a bad value. An application can word the messages itself from these three; only a suggestion such as "Did you mean --verbose?" and the commands an option of another command belongs to are left to the message. The token is raw, so escape control characters before printing it.
+A handler throws it with its command, which a parameter typed `Command` gets:
+
+```php
+function (Command $command, bool $stdin, array $paths): int {
+	if ($stdin && $paths) {
+		throw new UsageException('Paths cannot be combined with `--stdin`.', $command);
+	}
+	...
+}
+```
+
+The message writes code in backticks, as a description does, and `renderError()` draws it in color without them. To print the message your own way, `formatText()` of the renderer does the same for any text.
+
+The `reason` of a `ParseException` tells what was wrong, as a case of the `ParseFailure` enum, such as `ParseFailure::UnknownOption` or `ParseFailure::MissingArgument`, `parameter` is the parameter the error concerns, when there is one, and `token` the part of the command line it is about, as given: the name of an option as written, without its value, a command, the first unexpected argument or a bad value. An application can word the messages itself from these three; only a suggestion such as "Did you mean --verbose?" and the commands an option of another command belongs to are left to the message. The token is raw, so escape control characters before printing it.
 
 Common error messages:
 
 | Error | Cause |
 |-------|-------|
-| `Option --output requires a value.` | Option used without its required value |
-| `Option --verbose does not accept a value.` | A value given to a flag |
-| `Unknown option --verbos. Did you mean --verbose?` | Unrecognized option |
-| `Missing required argument <file>.` | Required argument not provided |
-| `Unexpected arguments 'b', 'c'.` | Extra positional arguments |
-| `Option --format: expects json or xml, 'yaml' given.` | Value not in the enum |
-| `Unknown command 'chekc'. Did you mean 'check'?` | Unrecognized command |
+| ``Option `--output` requires a value.`` | Option used without its required value |
+| ``Option `--verbose` does not accept a value.`` | A value given to a flag |
+| ``Unknown option `--verbos`. Did you mean `--verbose`?`` | Unrecognized option |
+| ``Missing required argument `<file>`.`` | Required argument not provided |
+| ``Unexpected arguments `b`, `c`.`` | Extra positional arguments |
+| ``Option `--format`: expects `json` or `xml`, `yaml` given.`` | Value not in the enum |
+| ``Unknown command `chekc`. Did you mean `check`?`` | Unrecognized command |
 | `Missing command.` | A command is required, but none was given |
-| `Option --generate-baseline belongs to command 'check'.` | Option of another command |
+| ``Option `--generate-baseline` belongs to command `check`.`` | Option of another command |
 
 Errors in the definition itself, such as an option name without a dash, a name used twice or a required argument after an optional one, are programming errors and throw `\InvalidArgumentException`.
 
 
@@ -27,7 +27,8 @@ final class HelpRenderer
 		'command' => '#87D787',
 		'value' => '#D78787',
 		'default' => '#767676', // also the dots of a repeatable parameter
-		'code' => '#87D7FF', // written in backticks in a description or a text
+		'code' => '#87D7FF', // written in backticks in a description, a text or a message
+		'error' => '#FF5F5F',
 	];
 
 	private const MaxSyntaxWidth = 28;
@@ -60,6 +61,19 @@ public function render(Command $command): void
 	}
 
 
+	/**
+	 * Writes the message of the error to the console, followed by the help of the command in which it went wrong.
+	 */
+	public function renderError(UsageException $e): void
+	{
+		if ($this->console === null) {
+			(new self(new Console, $this->width))->renderError($e);
+		} else {
+			$this->console->write($this->style('error', 'Error:') . ' ' . $this->formatText($e->getMessage()) . "\n\n" . $this->renderToString($e->command));
+		}
+	}
+
+
 	/**
 	 * Returns the help of the command, colored when there is a console.
 	 */
@@ -81,9 +95,7 @@ public function renderToString(Command $command): string
 				? [$this->style('heading', $item->title . ':')]
 				: [];
 			if ($item instanceof Text) {
-				$blocks[] = $this->console?->hasColors()
-					? implode('', array_map(fn(array $piece) => $piece[1] ? $this->style('code', $piece[0]) : $piece[0], self::splitCodeSpans($item->text)))
-					: $item->text;
+				$blocks[] = $this->formatText($item->text);
 			}
 		}
 
@@ -301,12 +313,30 @@ private function splitWords(string $text, ?string $role): array
 	}
 
 
+	/**
+	 * Returns the text with its code spans drawn in the color of code and without the backticks, the rest in the
+	 * given color of Console::color(); without colors the text as it is.
+	 */
+	public function formatText(string $text, ?string $color = null): string
+	{
+		if (!$this->console?->hasColors()) {
+			return $text;
+		}
+
+		$out = '';
+		foreach (self::splitCodeSpans($text) as [$piece, $code]) {
+			$out .= $code ? $this->style('code', $piece) : $this->console->color($color, $piece);
+		}
+
+		return $out;
+	}
+
+
 	/**
 	 * Splits the text at the code spans of Markdown into pieces of text and of code, the code without its backticks.
 	 * A span closes with a run of as many backticks as opened it, so code holding a backtick is written in a longer
 	 * run, and one space padding both sides of the code is dropped; a span does not cross a line.
 	 * @return list<array{string, bool}>  the piece and whether it is code
-	 * @internal
 	 */
 	public static function splitCodeSpans(string $text): array
 	{
@@ -324,6 +354,26 @@ public static function splitCodeSpans(string $text): array
 	}
 
 
+	/**
+	 * Writes the code as a code span that splitCodeSpans() reads back: control characters as escape sequences, since a
+	 * span does not cross a line, in a run of backticks longer than any inside, padded with a space where the padding
+	 * would otherwise be dropped or the code starts or ends with a backtick; empty code as the empty string of a shell.
+	 * @internal
+	 */
+	public static function formatCode(string $code): string
+	{
+		if ($code === '') {
+			return "`''`";
+		}
+
+		$code = addcslashes($code, "\0..\37\177");
+		preg_match_all('~`+~', $code, $m);
+		$fence = str_repeat('`', max([0, ...array_map(strlen(...), $m[0])]) + 1);
+		$pad = preg_match('~^`|`$|^ (?=.*\S).* $~s', $code) ? ' ' : '';
+		return $fence . $pad . $code . $pad . $fence;
+	}
+
+
 	/**
 	 * Returns the default value in words: the description of the default when there is one, otherwise a scalar value
 	 * or the value of an enum case, and null when there is nothing to show.
 
@@ -29,7 +29,7 @@ public static function int(?int $min = null, ?int $max = null): \Closure
 				: '';
 			$int = (int) $digits;
 			if ((string) $int !== $digits) { // (int) clamps a number out of the range of int
-				throw new \InvalidArgumentException("expects an integer, '$s' given.");
+				throw new \InvalidArgumentException('expects an integer, ' . HelpRenderer::formatCode($s) . ' given.');
 			}
 
 			self::checkRange($int, $min, $max);
@@ -49,7 +49,7 @@ public static function float(?float $min = null, ?float $max = null): \Closure
 			$s = (string) $value;
 			$float = (float) $s;
 			if (!preg_match('#^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$#D', $s) || !is_finite($float)) { // 1e9999 overflows to infinity
-				throw new \InvalidArgumentException("expects a number, '$s' given.");
+				throw new \InvalidArgumentException('expects a number, ' . HelpRenderer::formatCode($s) . ' given.');
 			}
 
 			self::checkRange($float, $min, $max);
@@ -74,9 +74,9 @@ private static function checkRange(int|float $number, int|float|null $min, int|f
 	{
 		if (($min !== null && $number < $min) || ($max !== null && $number > $max)) {
 			throw new \InvalidArgumentException(match (true) {
-				$max === null => "expects at least $min, $number given.",
-				$min === null => "expects at most $max, $number given.",
-				default => "expects a number from $min to $max, $number given.",
+				$max === null => "expects at least $min, `$number` given.",
+				$min === null => "expects at most $max, `$number` given.",
+				default => "expects a number from $min to $max, `$number` given.",
 			});
 		}
 	}
@@ -91,7 +91,7 @@ public static function realPath(): \Closure
 		return function (mixed $value): string {
 			$path = (string) $value === '' ? false : realpath((string) $value); // realpath('') is the working directory
 			return $path === false
-				? throw new \InvalidArgumentException("file path '$value' not found.")
+				? throw new \InvalidArgumentException('file path ' . HelpRenderer::formatCode((string) $value) . ' not found.')
 				: $path;
 		};
 	}
 
@@ -7,7 +7,7 @@
 
 namespace Nette\CommandLine\Parameters;
 
-use Nette\CommandLine\Command;
+use Nette\CommandLine\{Command, HelpRenderer};
 use function count, is_array, is_string;
 
 
@@ -86,9 +86,9 @@ private static function checkValues(array $values, string $name): array
 	public function normalize(string $value): mixed
 	{
 		if ($this->enum !== null && !in_array($value, $this->enum, true)) {
-			$enum = $this->enum;
+			$enum = array_map(HelpRenderer::formatCode(...), $this->enum);
 			$last = array_pop($enum);
-			throw new \InvalidArgumentException('expects ' . ($enum ? implode(', ', $enum) . " or $last" : $last) . ", '$value' given.");
+			throw new \InvalidArgumentException('expects ' . ($enum ? implode(', ', $enum) . " or $last" : $last) . ', ' . HelpRenderer::formatCode($value) . ' given.');
 		}
 
 		$result = $value;