Add Remix CLI

[mjackson]

This adds the initial Remix CLI through the published @remix-run/cli package and the generated remix package wrapper.

The CLI can:

• create a new app with npx remix new or an installed remix new
• scaffold AGENTS.md into new apps
• install and list official Remix skills with remix skills
• check project health and apply low-risk fixes with remix doctor
• inspect an app route tree with remix routes and remix routes --json

Create a new app

npx remix new my-app
cd my-app

Use the installed CLI

npm i remix
npx remix new my-app
cd my-app
npx remix routes
npx remix skills install

Smoke coverage

The remix package wrapper now has smoke tests for top-level help, command help, version output, shell completion, new, doctor, routes, and skills.

[github-actions]

Preview Build Available

A preview build has been created for this PR. You can install it using:

pnpm install "remix-run/remix#preview/pr-11204&path:packages/remix"

This preview build will be updated automatically as you push new commits.

[brookslybrand]

@mjackson this is great! I was going to suggest today that we remove the script from the Skill and leverage a CLI instead (ofc including directions in the skill to use it). Looks like you're 1 step ahead of me!

[remix-run-bot]

Changes in this PR resulted in updates to the auto-generated remix package in 52b47b1. Please review those changes prior to merging.

[github-actions]

Codex PR Review

Verdict: The PR is close, but there is one blocking versioning regression in the new remix CLI wrapper.

Findings:

• High: The generated remix wrapper sets REMIX_CLI_VERSION but never passes remixVersion into @remix-run/cli runtime context, and @remix-run/cli does not read REMIX_CLI_VERSION. As a result, remix new run via the remix package can scaffold with "remix": "latest" instead of the installed remix version, which can create version drift immediately after scaffold. Evidence: wrapper only sets env var and calls runCli(argv) in packages/remix/src/cli.ts:9; CLI context supports remixVersion in packages/cli/src/lib/cli.ts:14; scaffold default version falls back to latest in packages/cli/src/lib/bootstrap-project.ts:84.

Completeness:

• Published-package change files are present for @remix-run/cli, create-remix, and remix.
• Docs/readmes for the new CLI packages were added.
• Missing coverage for the wrapper-to-CLI version handoff path (packages/remix/src/cli.ts -> @remix-run/cli context), which is the path that regressed.

Validation:

• Ran diff/commit inspection against the provided SHAs only.
• Ran targeted tests with the required repo toolchain PATH (node v24.14.0, pnpm 10.32.1): pnpm --filter @remix-run/cli test, pnpm --filter create-remix test, pnpm --filter remix test.
• create-remix and remix tests passed; multiple @remix-run/cli tests failed at file level in this environment without detailed diagnostics, so I relied on direct code-path inspection for the reported issue.

[mjackson]

/codex Address the concerns in your comment above and push a new commit that fixes them.

[github-actions]

@mjackson Codex finished processing your request.

Codex Update

Request:

• Address the PR review concern that docs/release notes still mention remix skills status even though the CLI only supports install and list.

Changes:

• Updated packages/cli/README.md programmatic usage example from run(['skills', 'status']) to run(['skills', 'list']).
• Updated packages/cli/.changes/minor.initial-release.md to describe the remix skills install|list workflow (removed status).

Validation:

• pnpm --filter @remix-run/cli run typecheck passed.
• pnpm --filter @remix-run/cli run test failed in this environment because the package test script uses node --test './src/**/*.test.ts' and Node v20.20.1 here does not resolve that glob as expected (repo warns it expects Node >=24.3.0).
• node --test './packages/cli/src/lib/commands/skills.test.ts' also failed here due .ts test execution support in this Node runtime.

Risks:

• Residual validation gap: package tests could not be executed successfully in this environment due Node/runtime mismatch with the package’s expected engine.

Commit: bf157e3

[github-actions]

Codex PR Review

Verdict: No high-signal correctness, security, or performance issues found in the PR diff.

Findings:

• No meaningful issues found in the reviewed base/head diff (690199187712258736d082a73bbde0f5b03247ea...431badb6c29ad8f9fb9d0d6c47c5e04cc8e222e6).

Completeness:

• Published-package release notes are present (packages/cli, packages/create-remix, and packages/remix change files/changelog updates).
• Docs were updated for new CLI/create flows (README.md, packages/remix/README.md, plus new package READMEs).
• Minor gap: I did not find dedicated tests under packages/remix specifically asserting the generated remix/cli wrapper behavior (env handoff/version propagation), though CLI/create-remix behavior is heavily tested.

Validation:

• Reviewed commit list, --stat, and targeted unified diffs across package exports, generated wrapper code, scaffolding logic, and workflows.
• Ran PATH=/opt/hostedtoolcache/node/24.14.0/x64/bin:$PATH pnpm --filter create-remix run test (pass).
• Ran PATH=/opt/hostedtoolcache/node/24.14.0/x64/bin:$PATH pnpm --filter @remix-run/cli run test; this failed in this runner due Node warning noise from NO_COLOR+FORCE_COLOR affecting subprocess-based assertions, not an obvious product regression from the diff itself.

[github-actions]

Codex PR Review

Verdict: The feature scope is strong, but there is a blocking test reliability regression in the new CLI test suite.

Findings:

• High: Subprocess-based CLI tests don’t sanitize inherited test-runner env, and they fail under Node 24 test isolation with empty child output (example: packages/cli/src/index.test.ts:11, similarly packages/cli/src/lib/commands/routes.test.ts:270 and packages/cli/src/lib/commands/doctor.test.ts:1080). Repro I ran: node ./packages/cli/src/index.test.ts fails with AssertionError ... result.stdout === '' for the --help spawn case. This makes the new test coverage unstable/incorrect for CI and local runs.

Completeness:

• Change files were added for published packages (cli, create-remix, remix).
• README/docs coverage for new CLI/create-remix usage is present.
• Main implementation and tests for new, routes, doctor, skills, and wrapper entrypoints are included.

Validation:

• Ran (required wrapper): PATH="/home/runner/work/_temp/codex-toolchain-bin:$PATH" pnpm --filter @remix-run/cli test (failed; wrapper could not append to /home/runner/work/_temp/codex-validation-log.jsonl due read-only fs, and test run reported multiple failures).
• Ran direct diagnostics with repo Node binary to isolate behavior: node ./packages/cli/src/index.test.ts (fails with empty spawned stdout), node ./packages/cli/src/index.ts --help (works when run directly).

Machine-recorded validation evidence:

• No node/pnpm validation commands were recorded from the Codex session.

[github-actions]

Codex PR Review

Verdict: The PR is close, but it has one security issue that should be fixed before merge.
Findings:

• High: remix skills install trusts remote GitHub tree paths without normalizing/sanitizing path segments, then writes them with path.join. A malicious or compromised upstream tree entry like skills/../... or a file path containing ../ can escape the target skill directory and overwrite arbitrary files under the project root (or --dir root). This originates at skill/file path extraction and is exploitable at write time (packages/cli/src/lib/skills.ts:219, packages/cli/src/lib/skills.ts:226, packages/cli/src/lib/skills.ts:445).
  Completeness:
• Published-package completeness looks good overall: new packages include changelog/change files, READMEs, and tests.
• Missing hardening coverage for path traversal on remote skill names/file paths (should include rejection tests for .., absolute paths, and normalized-escape cases).
  Validation:
• Ran: export PATH="/tmp/codex-toolchain-bin.VmLMAc:$PATH"; pnpm --filter create-remix test (pass).
• Ran: export PATH="/tmp/codex-toolchain-bin.VmLMAc:$PATH"; pnpm --filter @remix-run/cli test (fail; 4 failing test files in this environment).
• Ran targeted follow-ups: node --test './src/index.test.ts' and node --test './src/lib/commands/routes.test.ts' under packages/cli (both fail in this environment).

Machine-recorded validation evidence:

• pnpm --filter create-remix test in /home/runner/work/remix/remix exited 0
• pnpm --filter @remix-run/cli test in /home/runner/work/remix/remix exited 1
• node --test ./src/index.test.ts in /home/runner/work/remix/remix/packages/cli exited 1
• node --test ./src/lib/commands/routes.test.ts in /home/runner/work/remix/remix/packages/cli exited 1
• node --test --test-reporter=spec ./src/index.test.ts in /home/runner/work/remix/remix/packages/cli exited 1
• node ./src/index.test.ts in /home/runner/work/remix/remix/packages/cli exited 1
• node ./src/index.ts --help in /home/runner/work/remix/remix/packages/cli exited 0
• node ./src/lib/commands/routes.test.ts in /home/runner/work/remix/remix/packages/cli exited 1

[github-actions]

Codex PR Review

Verdict: Needs one follow-up fix: Remix version handoff from the generated remix wrapper is currently ineffective.

Findings:

• High: The generated wrapper sets process.env.REMIX_CLI_VERSION (cli.ts:10), but version resolution never reads that env var (remix-version.ts:10). Inference from the code paths: when require.resolve('remix') from cwd fails (for example, invoking the installed CLI outside a project), remix version can return RMX_REMIX_VERSION_UNAVAILABLE instead of the wrapper’s own version, and remix new falls back to latest instead of the invoking Remix version.

Completeness:

• Change files are present for @remix-run/cli, create-remix, and the remix export update, and README/docs updates were included.
• Missing coverage for wrapper-to-CLI version propagation (REMIX_CLI_VERSION), which is the path currently regressing.

Validation:

• Current CI status from context is mostly in_progress (build, lint, typecheck, tests, integrations, change-file validation, preview); one test (windows-latest) job is skipped.
• This review did not run additional validations (no tests/lint/typecheck/build executed locally).

[github-actions]

Codex PR Review

Verdict: The PR is close, but it has one functional regression in version propagation through the new remix CLI wrapper.
Findings:

• High: remix new does not reliably scaffold with the installed remix package version because the wrapper sets REMIX_CLI_VERSION but @remix-run/cli never reads it. In packages/remix/src/cli.ts, the wrapper writes process.env.REMIX_CLI_VERSION then calls runCli(argv) without runtime context. The CLI default version path in packages/cli/src/lib/bootstrap-project.ts only checks REMIX_VERSION or getRuntimeRemixVersion() and otherwise falls back to 'latest', so remix new can ignore the installed version and scaffold with remix: "latest" unintentionally.
  Completeness:
• Change files are present for published package impacts (@remix-run/cli, create-remix, and remix exports update).
• README/docs updates for the new CLI and create-remix are included.
• Missing coverage: there is no integration test asserting that remix/cli wrapper invocation propagates the Remix version into scaffolded package.json.
  Validation:
• CI summary in the provided context shows all listed checks passing (build, test, lint, typecheck, integrations, and change-file validation).
• This review did not run additional validations locally.

[remix-run-bot]

Changes in this PR resulted in updates to the auto-generated remix package in 54e1b9f. Please review those changes prior to merging.

[github-actions]

Codex PR Review

Verdict: The PR is largely complete, but it introduces a filesystem write-escape risk in skills install that should be fixed before merge.
Findings:

• High: remix skills install writes remote file paths from GitHub without path normalization or boundary checks, so a skills/<name>/../../... tree entry would write outside the intended skills directory (packages/cli/src/lib/skills.ts:226, packages/cli/src/lib/skills.ts:445). Even if the source repo is trusted today, this is a supply-chain attack surface; normalize and reject absolute/.. segments before writing.
  Completeness:
• Published-package release metadata appears present (packages/cli/.changes, packages/create-remix/.changes, packages/remix/.changes) and docs/readmes were updated.
• Missing hardening coverage for the path-safety case above (no test asserting that remote skill paths cannot escape skillsDir).
  Validation:
• This review did not run tests/lint/typecheck/build (per workflow instructions).
• Context CI summary shows all reported checks passing (build/test/lint/typecheck/change-file validation and integration jobs).

[github-actions]

Codex PR Review

Verdict: I did not find any high-signal correctness, security, or regression issues in the reviewed diff.

Findings:

• No meaningful issues found in the PR diff between 690199187712258736d082a73bbde0f5b03247ea and d90d76c5902237d127d585a2c5d34a0f5509edad.

Completeness:

• The new published packages (@remix-run/cli, create-remix) include tests, README files, and change files.
• remix export/bin integration for remix/cli is accompanied by docs and a change file.
• The CLI bootstrap/component-returning-function pattern matches existing local conventions and the provided reference examples.

Validation:

• This review did not run tests/lint/typecheck/build commands.
• Context-reported CI for this head SHA is green across build, test, lint, typecheck, change-file validation, and relevant integration checks.

[github-actions]

Codex PR Review

Verdict: The PR is close, but doctor currently misclassifies common valid engines.node ranges.

Findings:

• packages/cli/src/lib/doctor/environment.ts:255 only parses comparator-style ranges via parseComparator() (<=, >=, <, >, =) and rejects standard npm semver syntaxes like ^24.3.0, ~24.3.0, or 24.x (:303-318). In real projects this will produce false node-engine-unparseable findings and, with --fix, overwrite a valid constraint to >=24.3.0, changing intended version policy rather than preserving it.

Completeness:

• New published packages (@remix-run/cli, create-remix) include tests, READMEs, changelogs, and .changes entries.
• remix export/bin updates are present with a matching change file.
• Missing piece relative to behavior: add coverage for common semver range forms in environment doctor tests (e.g. caret/tilde/x-ranges), or switch to a standards-compliant semver range evaluator.

Validation:

• This review did not run tests/lint/typecheck/build commands (per instructions).
• Context file reports all relevant CI checks as success (build/test/lint/typecheck/change-file validation plus integration suites).

[github-actions]

Codex PR Review

Verdict: The PR is close, but doctor --fix has a security-sensitive path handling bug and a codegen correctness bug.

Findings:

• High: doctor --fix can write outside the app root when route keys contain path traversal segments. Route keys are accepted as-is from app/routes.ts, transformed without sanitizing / or .., then used to build fix paths and written via path.join(appRoot, fixPlan.path) without containment checks. This allows out-of-root writes from untrusted project route maps. Evidence: packages/cli/src/lib/controller-files.ts:6, packages/cli/src/lib/controller-files.ts:42, packages/cli/src/lib/doctor/fixes.ts:13.
• Medium: placeholder action generation uses routeNode.key directly as an identifier (export const ${routeNode.key}), which produces invalid JS/TS for non-identifier route keys (for example quoted keys with -, spaces, etc.). This makes some doctor --fix outputs uncompilable. Evidence: packages/cli/src/lib/doctor/controllers.ts:331, packages/cli/src/lib/doctor/controllers.ts:349.

Completeness:

• Change files, docs, and broad test coverage for new CLI/create-remix functionality appear present.
• Aside from the findings above, the PR scope (CLI + wrapper + create-remix + release plumbing) looks complete.

Validation:

• CI context shows all listed checks passing (build/test/lint/typecheck/integration and change-file validation).
• This review did not run additional validation commands locally.

[github-actions]

Codex PR Review

Verdict: No blocking issues found in the PR diff; this looks ready to merge.

Findings:

• No meaningful issues identified in the reviewed diff.

Completeness:

• The PR appears complete for its stated scope: new @remix-run/cli, create-remix, and remix/cli wiring are present with corresponding docs and change files.
• Coverage for core CLI flows appears present via added tests across cli and create-remix.
• I did not find a missing published-package change file for the modified published packages in this diff.

Validation:

• This review did not run additional validations (per workflow constraints).
• Context file reports all required CI checks succeeded (build/test/typecheck/lint/integration/change-file validation).

[github-actions]

Codex PR Review

Verdict: The PR is broadly solid, but there is one option-parsing regression that should be fixed before merge.

Findings:

• parseArgs accepts another flag token as a string option value instead of treating it as a missing value (e.g. --app-name --force, --dir --json), which can silently alter command behavior and suppress expected usage errors. This comes from taking argv[index + 1] without validating it in parse-args.ts . It affects commands that depend on string options like new and skills (see new.ts and skills.ts).

Completeness:

• Release-note/change files are present for published package changes (packages/cli, packages/create-remix, and packages/remix).
• README/docs updates for the new CLI surfaces are included.
• Missing coverage: no test currently asserts that a string option followed by another flag throws a missing-value error in parse-args.test.ts.

Validation:

• CI summary in the provided context shows all required checks passed (build, test, lint, typecheck, integrations, and change-file validation).
• This review did not run additional validations locally (per review-only workflow).

[github-actions]

Codex PR Review

Verdict: No blocking issues found in the reviewed diff.

Findings:

• No meaningful issues found in the PR diff after reviewing the new CLI/create-remix implementation, remix wrapper export/bin wiring, and release-script/workflow updates.

Completeness:

• Published-package changes appear complete: new packages include README/CHANGELOG/LICENSE and .changes entries, and packages/remix includes the corresponding export/bin update plus change file.
• The PR includes substantial targeted tests for new behavior (cli, create-remix, routes, skills, doctor, parsing/reporting), so coverage for core added functionality looks present.

Validation:

• This review did not run additional validation commands (per review-only instructions).
• Context file CI summary shows all reported checks passing for head e9ab595844b3556949d7ca316c738ada56d6f995 (build/test/lint/typecheck/integration and change-file validation).

[github-actions]

Codex PR Review

Verdict: The PR is close, but it has one high-impact path-safety issue in skills install.

Findings:

• High: skills install trusts remote skill/archive path segments and uses them directly in filesystem mutation paths (fs.rm and fs.writeFile) without containment enforcement. In skills.ts and skills.ts, remoteSkill.name/file.path are joined into local paths but never checked with a guard like resolveContainedPath, so malformed or compromised metadata could escape skillsDir and trigger out-of-scope deletes/writes.

Completeness:

• The PR appears complete on docs/changefiles/export wiring for @remix-run/cli, create-remix, and remix/cli.
• Missing targeted tests for hostile archive paths (../, absolute-like segments) in the skills install pipeline.

Validation:

• Context CI summary is fully green (build, tests, lint, typecheck, integrations, change-file validation).
• This review did not run additional validations.

[github-actions]

Codex PR Review

Verdict: Solid feature scope overall, but there is one high-impact path traversal issue in skills installation.

Findings:

• High: remix skills install can write files outside the target skills directory if a remote skill file path contains traversal segments (.. or absolute paths). file.path is derived from remote metadata/archive paths without containment checks and then written via path.join(skillDir, file.path) and fs.writeFile(...), which can escape skillDir and overwrite arbitrary files under the current user permissions (skills.ts, skills.ts, skills.ts). This should be guarded with path normalization + containment enforcement (similar to resolveContainedPath) before any write.

Completeness:

• Change files are present for @remix-run/cli, create-remix, and remix export/bin updates.
• CLI/docs/tests coverage appears broad for command behavior.
• Missing piece: no test currently asserts rejection/sanitization of malicious remote skill file paths before writing.

Validation:

• CI status from the provided context is all green (build/test/typecheck/lint/integrations/change-file validation all succeeded).
• This review did not run additional validations locally (per workflow constraints).

[github-actions]

Codex PR Review

Verdict: The PR looks solid overall, and I did not find any high-signal issues in the diff.

Findings:

• No meaningful issues found in the reviewed diff.

Completeness:

• Published-package metadata appears complete for the new @remix-run/cli and create-remix packages (package files, READMEs, changelogs, and .changes entries are present).
• The remix package wiring for the new CLI wrapper (./cli export + remix bin) is included and aligned with the generated-file flow.
• Command-level tests are extensive across the new CLI areas (new, routes, skills, doctor, completion, and create-remix forwarding behavior).

Validation:

• CI status in the provided context is green across build, test, typecheck, lint, integration suites, and change-file validation.
• This review did not run additional validations locally (per review-only workflow).

[github-actions]

Codex PR Review

Verdict: I did not find any correctness, security, or performance regressions in the reviewed diff.

Findings:

• No meaningful issues found in the PR diff.

Completeness:

• The shipped diff appears complete for the implemented scope: new @remix-run/cli, remix/cli export/bin wiring, scaffold assets, tests, docs, and change files are present.
• The PR body in context still describes adding create-remix, but the final head commit removes that package; update the PR description to match the landed scope.

Validation:

• CI status from the provided context is fully green (build/test/lint/typecheck/change-file checks all succeeded).
• This review did not run any additional validation commands.

[remix-run-bot]

Changes in this PR resulted in updates to the auto-generated remix package in 3f20f21. Please review those changes prior to merging.

[github-actions]

Codex PR Review

Verdict: The CLI feature set is substantial and mostly well-covered, but there is one correctness issue in the programmatic cwd handling.

Findings:

• run(argv, context) exposes a cwd override but core commands still resolve against process.cwd(), so programmatic callers can target the wrong project/directory. run() sets runtime context with cwd (cli.ts), but skills uses process.cwd() directly (skills.ts), routes calls loadRouteMap() with its default process.cwd() (routes.ts, route-map.ts), doctor calls checkEnvironment() with its default process.cwd() (doctor.ts, environment.ts), and new resolves relative paths with path.resolve(...) from the real process cwd (bootstrap-project.ts). This makes run([...], { cwd }) non-functional for actual filesystem targeting.

Completeness:

• Change files are present for published package impact (packages/cli and packages/remix).
• Command/test coverage is broad, but I did not find a test that asserts run(..., { cwd }) behavior, which would have caught the issue above.

Validation:

• CI summary in the provided context shows all listed checks passing (build/test/lint/typecheck/integration suites and change-file validation).
• This review did not run additional validations (per review-only instructions).

[github-actions]

Codex PR Review

Verdict: The PR looks solid and ready to merge from a review-only perspective.

Findings:

• No meaningful issues found in the diff after reviewing core CLI logic (new, doctor, routes, skills), path-safety handling, package wiring, docs, and release-note coverage.

Completeness:

• The published-package changes are accompanied by change files (packages/cli/.changes/minor.initial-release.md and packages/remix/.changes/minor.remix.update-exports.md).
• The PR includes substantial command-level and wrapper smoke test coverage for the newly added CLI surface.
• README/docs updates for both remix and @remix-run/cli are present and aligned with the stated feature set.

Validation:

• This review did not run additional validations (per review workflow constraints).
• Context CI summary shows all relevant checks passing, including build/test/lint/typecheck, integration suites, and change-file validation.