`argent flow run` now takes an explicit YAML path instead of a
saved-flow name:
```
argent flow run .argent/flows/checkout.yaml --platform ios
```
The path may point anywhere on the local filesystem; the filename stem
names the run's report/artifacts, so it must be `[A-Za-z0-9_-]+` with a
lowercase `.yaml` extension. A bare name fails with the exact
replacement command, and `argent flow list` prints paths instead of
names.
Because sibling `run:` files and `__baselines__` resolve beside the
YAML, the CLI now requires the auto-started local tool server and
refuses `ARGENT_TOOLS_URL` / `argent link` routing. The `flow-execute`
tool stays remotely callable via `name` + `project_root`, and gains a
`flow_path` parameter (exactly one of `name`/`flow_path`) that is only
honored when the file-input boundary verified it as a real host path —
uploads and boundary bypasses are rejected, so it can't execute
arbitrary server YAML.
Also: the flow-name pattern is now a single shared export from
`@argent/registry`, and the recorder composes a `flow_path` call into a
`run:` step when it targets a sibling of the recording.
Fixes#638.
## The report understated it
The issue says `argent mcp --help` "does not hang and does not start the
server — it simply prints
nothing". Reproducing it showed the opposite:
```
$ argent mcp --help < /dev/null ; echo $?
0 # 0 bytes ← what the reporter saw
$ argent mcp --help # stdin open (a pipe, an editor, a CI step)
# HANGS — I hit a 300s timeout
```
`--help` **starts the MCP stdio server**, which blocks reading JSON-RPC
from stdin. The "prints
nothing, exit 0" is just the server getting an immediate EOF from a
closed stdin. So this is the same
"`--help` runs the real command" bug that was fixed for the installers —
`mcp` was missed.
`startMcpServer` takes no argv at all (`mcp-server.ts:96` — its only
parameter is `{ paths }`), so a
help flag was *structurally* unreachable; there was nowhere downstream
that could have handled it.
## Fix
`mcp` joins the existing guarded set rather than growing a second help
path. That set's defining
property is "the handler never inspects its argv", and `mcp` qualifies
more strongly than the
installers do — it isn't merely ignoring `rest`, it is never handed it.
**It cannot fire on a real launch.** The guard tests `rest`, which is
`[]` for every generated editor
config (all four shapes end at `mcp`, and `isArgentManagedEntry`
requires exactly that), and
`[].some(...)` evaluates no predicate. This is pinned in both
directions, because a guard that *did*
fire here would print usage onto the JSON-RPC channel and break every
editor at handshake — the
highest-cost regression in this file, and it was untested.
The top-level table's `mcp` row now reads the same metadata as its own
help, so the two cannot drift.
**No rename.** An earlier draft renamed the module and six identifiers
(`installer-help` →
`command-help`, etc.) on the grounds that its comments had become false.
They hadn't quite: fixing
`mcp` *and* `tools` makes "every other subcommand parses `--help`
itself" true again — I checked all
ten siblings. Since #530 and #568 both edit `cli.ts`, a rename would
have forced them through churn
for no behavioural gain. Prose-only.
## Second commit: `argent tools --help`
The issue mentions it in passing; it's a different mechanism and a
genuinely dead branch.
`argv.filter((a) => !a.startsWith("--"))` dropped `--help` before the
subcommand was read, so it fell
through to listing all 77 tools — **contacting the tool-server, starting
one if none was running**,
to do it. Only `-h` ever reached the existing help branch.
Scoped to the subcommand position on purpose: a global check would have
broken
`argent tools describe <name> --help`, which today prints *that tool's*
flags. It still does — there
is a test.
Separate commit so it can be reverted alone.
## Verification
Live, against the built CLI:
| | before | after |
|---|---|---|
| `mcp --help`, stdin open | hangs indefinitely | usage, returns
immediately |
| `mcp --help`, stdin closed | 0 bytes, exit 0 | 849 bytes of help, exit
0 |
| `mcp` (real launch) | works | works — verified with an actual
`initialize` handshake, server replies with its capabilities |
| `mcp --metro-port 8082` | starts server | starts server (guard keys on
help, not on "any argv") |
| `tools --help` | 77-line catalogue | usage |
| `tools describe gesture-tap --help` | tool's flags | tool's flags |
| `argent --help` `mcp` row | — | byte-identical |
argent 80 passed, argent-cli 284 passed.
## Note on the help text
Every claim in it is sourced (stdio/JSON-RPC transport, stdout
ownership, the `~/.argent/mcp-calls.log`
default and `ARGENT_MCP_LOG` override, auto-spawn vs
`ARGENT_TOOLS_URL`/`argent link`). It deliberately
does **not** suggest running `argent mcp` by hand to check an install —
that is the reported hang — and
instead says it will look like it has hung and why.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## The bug
`argent <cmd> --help` for the installer subcommands `init` / `install` /
`update` / `uninstall` / `remove` did not print help — it ran the real,
side-effecting command. `argent uninstall --help` even opened the
destructive "Remove argent configuration from this workspace?" prompt
(with Yes pre-selected).
Root cause: `main()` in `packages/argent/src/cli.ts` dispatched these
subcommands and forwarded `rest` (including `--help`) to the installer
functions, which have no help handling. Only the top-level `--help` case
called `printHelp()`.
## The fix
Intercept `--help`/`-h` for exactly the installer command set before
dispatching, and print a short per-subcommand usage block without
loading or invoking any installer code (no network, no wizard, no
prompt).
- New side-effect-free module `packages/argent/src/installer-help.ts`
exports the pure decision function `installerHelpRequested(command,
rest)` plus `printInstallerHelp(command)`.
- `cli.ts` calls the guard at the top of `main()` and returns early when
help is requested.
- The other subcommands (`run`, `tools`, `server`, `link`, `flags`,
`enable`, `disable`, `telemetry`) already handle `--help` themselves, so
they are deliberately excluded — `argent run <tool> --help` still prints
that tool's flags.
## Verification
- `npm run build` (root tsc) + `npm run build -w @swmansion/argent` —
green.
- Ran the built CLI end-to-end (stdin from /dev/null): `init --help`,
`update --help`, `uninstall --help`, `install --help`, `remove --help`,
`uninstall -h` all print usage and exit 0 with no wizard/network/prompt.
- Regression: `argent --help` still prints top-level help; `argent run
--help` still prints the `run` usage (not intercepted).
- Added unit tests in `packages/argent/test/installer-help.test.ts` for
`installerHelpRequested` / `isInstallerCommand` (8 tests, all pass).
- `prettier` and `eslint` clean on the touched files; test typecheck
passes.
Fixes#451
Jakub Piasecki