Skip to content

CLI Agent mode#945

Merged
yamcodes merged 25 commits into
mainfrom
924-is-the-cli-llm-friendly
May 12, 2026
Merged

CLI Agent mode#945
yamcodes merged 25 commits into
mainfrom
924-is-the-cli-llm-friendly

Conversation

@yamcodes
Copy link
Copy Markdown
Owner

@yamcodes yamcodes commented May 12, 2026

Closes #924

Summary by CodeRabbit

  • New Features

    • Added --agent, --quiet, --json, and --yes flags for non-interactive, machine-readable CLI runs; --agent enables a one-shot automated init (yes+quiet+json).
    • CLI now suggests/install the ArkEnv AI skill during setup when appropriate.
  • Behavior / UX

    • Quiet mode suppresses spinners/ANSI output; JSON mode emits structured result to stdout and routes other output to stderr.
    • Help text updated to list the new flags.
  • Documentation

    • Docs and skill guidance updated to describe agent-mode workflow.

@yamcodes yamcodes linked an issue May 12, 2026 that may be closed by this pull request
@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented May 12, 2026

🦋 Changeset detected

Latest commit: d204eeb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@arkenv/cli Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@yamcodes yamcodes changed the title make plan CLI Agent mode May 12, 2026
@github-actions github-actions Bot added the docs Improvements or additions to documentation label May 12, 2026
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 12, 2026

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 89d55fdb-e460-419e-9716-c58e400ab113

📥 Commits

Reviewing files that changed from the base of the PR and between 25af06d and d204eeb.

📒 Files selected for processing (6)
  • .changeset/gold-ideas-grin.md
  • openspec/changes/cli-agent-mode/proposal.md
  • openspec/changes/cli-agent-mode/specs/scaffolding-cli/spec.md
  • openspec/changes/cli-agent-mode/tasks.md
  • packages/cli/src/commands/init.ts
  • packages/cli/src/lib/logger.ts

Walkthrough

This PR adds an agent-friendly, non-interactive mode to @arkenv/cli (flags: --yes, --quiet, --json, --agent), refactors CLI arg handling into a CLI class, implements a Logger supporting quiet/JSON modes, reorganizes Help/Init commands, updates prompts/scaffold for agent flows and optional skill install, and updates docs/specs/skill guidance and a changeset.

Changes

CLI Agent Mode (single cohesive cohort)

Layer / File(s) Summary
Design, spec, tasks, and proposal
openspec/changes/cli-agent-mode/*
Adds design, proposal, spec, tasks checklist and an OpenSpec entry defining --yes, --agent, --quiet, --json, stdout/stderr/JSON semantics, spinner suppression, and testing requirements.
Argument parsing and CLI facade
packages/cli/src/cli.ts, packages/cli/src/index.ts
New CLI class parses argv, computes booleans (short/long aliases), implements --agent as macro forcing isYes/isQuiet/isJson, constructs Logger, and centralizes entry routing to Help or Init with unified error handling.
Logger and output modes
packages/cli/src/lib/logger.ts
New LoggerOptions/Logger that routes stdout/stderr, strips ANSI in quiet mode, emits structured JSON on --json, provides spinner abstraction compatible with agent mode, and lifecycle helpers (cancel, fatal, finish) that emit JSON payloads when appropriate.
Help command and docs
packages/cli/src/commands/help.ts, apps/www/content/docs/cli/index.mdx
Adds HelpCommand and updates CLI docs to list --quiet, --json, and --agent (documents --agent as a macro).
Init command workflow (agent-aware)
packages/cli/src/commands/init.ts
InitCommand.run() now manages interactive/stdout behavior, checks/prompts for TS strictness, invokes runPromptWizard (agent-aware), scaffolds, optionally runs dependency install, optionally attempts skill installation (yamcodes/arkenv), and reports structured completion/errors through Logger.
Prompts and scaffold adjustments
packages/cli/src/prompts.ts, packages/cli/src/scaffold.ts
ProjectOptions adds overwrite, envKeys, installSkill; runPromptWizard accepts isAgent and skips the install prompt in agent mode; scaffold() detects package manager earlier, computes installCmd sooner, and returns packageManager/installCmd in early and final returns.
Skill docs and release metadata
skills/arkenv/SKILL.md, .changeset/gold-ideas-grin.md
SKILL.md adds an “Agent Setup (Machine-Readable)” section recommending pnpm dlx @arkenv/cli@latest init --agent and JSON verification; changeset entry documents the patch release.
Package/tooling and removed metadata
packages/cli/package.json, .gemini/commands/arkenv.toml
Adds test:run and typecheck scripts to packages/cli/package.json; removes previously embedded command metadata from .gemini/commands/arkenv.toml.
sequenceDiagram
    participant Agent as Agent
    participant CLI as CLI Parser
    participant Cmd as Init Command
    participant Logger as Logger
    participant Prompts as Prompt Wizard
    participant Scaffold as Scaffold
    participant Skills as Skill Installer
    participant IO as stdout/stderr

    Agent->>CLI: invoke (argv includes --agent / flags)
    CLI->>Logger: construct Logger(flags)
    CLI->>Cmd: dispatch command (init)
    Cmd->>Logger: interactiveStdout(true)
    Cmd->>Prompts: runPromptWizard(isAgent)
    alt isAgent
        Prompts-->>Cmd: fast defaults (no install prompt)
    else interactive
        Prompts-->>Cmd: user choices (may include installSkill)
    end
    Cmd->>Logger: interactiveStdout(false)
    Cmd->>Scaffold: scaffold(options)
    Scaffold-->>Cmd: { tsConfigResult, installCmd, packageManager }
    Cmd->>Cmd: run installCmd (if present)
    Cmd->>Skills: dlx skills add yamcodes/arkenv (optional)
    Cmd->>Logger: finish(message, details)
    alt isJson
        Logger->>IO: JSON payload to stdout, other output to stderr
    else normal
        Logger->>IO: human-readable outro to stdout/stderr
    end
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • yamcodes/arkenv#944: Overlapping changes to post-scaffold skill-install messaging and package-manager-aware dlx handling.
  • yamcodes/arkenv#904: Related edits to scaffold.ts / prompts.ts affecting returned installCmd/packageManager and prompt fields.
  • yamcodes/arkenv#947: Overlaps in updates to skills/arkenv/SKILL.md for agent-focused setup guidance.

Suggested labels

skills, enhancement, arkenv

Poem

🐰 I nibble flags in morning light,

--agent hums, the prompts take flight,
JSON whispers, spinners sleep,
Quiet runs that robots keep,
ArkEnv wakes and hops delight.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'CLI Agent mode' clearly summarizes the main change—adding agent-friendly CLI functionality with new flags and modes.
Linked Issues check ✅ Passed The PR implements comprehensive CLI agent mode support with --agent flag, --yes/--quiet/--json flags, and related skill installation prompts, directly addressing the LLM-friendliness objective of issue #924.
Out of Scope Changes check ✅ Passed All changes focus on implementing agent mode: CLI flag parsing, logger refactoring, command structure, skill installation prompts, and related documentation—all directly supporting the agent-friendly CLI objective.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch 924-is-the-cli-llm-friendly

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions github-actions Bot added the @arkenv/cli Issues or Pull Requests involving the ArkEnv CLI label May 12, 2026
@pkg-pr-new
Copy link
Copy Markdown

pkg-pr-new Bot commented May 12, 2026

Open in StackBlitz

arkenv

npm i https://pkg.pr.new/arkenv@945

@arkenv/bun-plugin

npm i https://pkg.pr.new/@arkenv/bun-plugin@945

@arkenv/cli

npm i https://pkg.pr.new/@arkenv/cli@945

@arkenv/fumadocs-ui

npm i https://pkg.pr.new/@arkenv/fumadocs-ui@945

@arkenv/vite-plugin

npm i https://pkg.pr.new/@arkenv/vite-plugin@945

commit: 25af06d

@arkenv-bot
Copy link
Copy Markdown
Contributor

arkenv-bot Bot commented May 12, 2026

📦 Bundle Size Report

No results found

All size limits passed!

@github-actions github-actions Bot added the www Improvements or additions to arkenv.js.org label May 12, 2026
@yamcodes yamcodes marked this pull request as ready for review May 12, 2026 12:17
@arkenv-bot
Copy link
Copy Markdown
Contributor

arkenv-bot Bot commented May 12, 2026

🤖 Hi @yamcodes, I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

@arkenv-bot
Copy link
Copy Markdown
Contributor

arkenv-bot Bot commented May 12, 2026

🤖 I'm sorry @yamcodes, but I was unable to process your request. Please see the logs for more details.

@arkenv-bot
Copy link
Copy Markdown
Contributor

arkenv-bot Bot commented May 12, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Warning

Rate limit exceeded

@yamcodes has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 1 minute and 6 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered by pushing new commits to this PR or by re-running the workflow.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

We enforce hourly and daily rate limits to ensure stability and fair usage of resources.

Project Deployment Review Updated (Asia/Almaty)
arkenv Ready Ready Preview, Comment May 12 2026, 5:20 PM (Asia/Almaty)

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 7

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.changeset/gold-ideas-grin.md:
- Line 9: Update the release note phrase "non `--agent` mode" to use a
hyphenated compound modifier: change it to "non-`--agent` mode" so the modifier
correctly binds to `--agent`; locate the text containing the exact phrase "non
`--agent` mode" in the .changeset release note and replace it with
"non-`--agent` mode".

In `@openspec/changes/cli-agent-mode/proposal.md`:
- Line 3: The proposal text claims that `--yes` is the canonical instruction for
the yamcodes/arkenv skill but the rest of the change establishes `--agent` as
the agent-facing canonical flag; update the wording so the canonical flag is
consistent—either change the sentence that mentions `--yes` to reference
`--agent` or change all occurrences of `--agent` to `--yes` throughout the
proposal; ensure the canonical-flag sentence and all examples/definitions use
the same flag name (referencing `--yes` and `--agent` as unique identifiers to
locate and fix the mismatch).

In `@openspec/changes/cli-agent-mode/specs/scaffolding-cli/spec.md`:
- Line 68: Update the usage/help-text requirement to include the new flag by
adding `--agent` alongside the existing flags: change the sentence that
currently requires descriptions for `--yes`, `--quiet`, and `--json` so it now
also requires a description for `--agent`; ensure the updated wording refers to
the usage text/ help text (usage text SHALL include descriptions for `--yes`,
`--quiet`, `--json`, and `--agent`) and adjust any related examples or scenarios
that assert presence of these flags in the help output.
- Line 70: Remove the malformed trailing requirement line "ND** the process
SHALL exit with code `0`" from the spec (it is a corrupted/duplicated line);
delete that exact string so only the valid requirement "the process SHALL exit
with code `0`" remains, ensure the file ends cleanly with a single newline, and
run the spec linter/formatter to confirm no other stray tokens remain.

In `@openspec/changes/cli-agent-mode/tasks.md`:
- Around line 3-35: The tasks file was committed with all checklist items marked
complete; revert the checklist items in openspec/changes/cli-agent-mode/tasks.md
to start unchecked so progress is traceable (change each "- [x]" to "- [ ]" for
items 1.1–5.5) and leave completed state flips for follow-up commits; ensure new
openspec/changes/<branch>/tasks.md files are initialized with unchecked items by
default going forward.

In `@packages/cli/src/commands/init.ts`:
- Around line 21-60: The stdout redirection started by
logger.interactiveStdout(true) may never be restored if an exception or early
return occurs; wrap the code from logger.interactiveStdout(true) through the
point where stdout is restored in a try/finally and call
logger.interactiveStdout(false) in the finally block so restoration always runs.
Concretely, call logger.interactiveStdout(true) before the block that calls
checkTsConfig(), the confirm prompt, detectFramework(), and runPromptWizard(),
then place all that logic inside a try { ... } and put
logger.interactiveStdout(false) inside finally { ... } to guarantee cleanup even
if checkTsConfig, confirm, detectFramework, or runPromptWizard throw or return
early. Ensure no other early exits bypass the finally and remove the standalone
restore call after runPromptWizard.

In `@packages/cli/src/lib/logger.ts`:
- Around line 90-108: The JSON error responses emitted by cancel() and fatal()
should match the success shape used by finish(): use a top-level status "error"
and a details object (not a bare message or error field). Update cancel(message)
to call this.json({ status: "error", details: { message } }) and update
fatal(message, error?) to call this.json({ status: "error", details: { message,
error: error instanceof Error ? error.message : error ? String(error) :
undefined } }) (include the error message only when present). Keep the existing
process.exit(0) / process.exit(...) behavior and toggle via this.options.isJson
as currently implemented.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 179f3136-e3b8-4833-91b9-ac1af3a4461d

📥 Commits

Reviewing files that changed from the base of the PR and between fe2ff79 and a07e6a3.

📒 Files selected for processing (18)
  • .changeset/gold-ideas-grin.md
  • .gemini/commands/arkenv.toml
  • apps/www/content/docs/cli/index.mdx
  • openspec/changes/cli-agent-mode/.openspec.yaml
  • openspec/changes/cli-agent-mode/design.md
  • openspec/changes/cli-agent-mode/proposal.md
  • openspec/changes/cli-agent-mode/specs/cli-agent-mode/spec.md
  • openspec/changes/cli-agent-mode/specs/scaffolding-cli/spec.md
  • openspec/changes/cli-agent-mode/tasks.md
  • packages/cli/package.json
  • packages/cli/src/cli.ts
  • packages/cli/src/commands/help.ts
  • packages/cli/src/commands/init.ts
  • packages/cli/src/index.ts
  • packages/cli/src/lib/logger.ts
  • packages/cli/src/prompts.ts
  • packages/cli/src/scaffold.ts
  • skills/arkenv/SKILL.md
💤 Files with no reviewable changes (1)
  • .gemini/commands/arkenv.toml

Comment thread .changeset/gold-ideas-grin.md Outdated
Comment thread openspec/changes/cli-agent-mode/proposal.md Outdated
Comment thread openspec/changes/cli-agent-mode/specs/scaffolding-cli/spec.md Outdated
Comment thread openspec/changes/cli-agent-mode/specs/scaffolding-cli/spec.md Outdated
Comment thread openspec/changes/cli-agent-mode/tasks.md Outdated
Comment thread packages/cli/src/commands/init.ts Outdated
Comment thread packages/cli/src/lib/logger.ts
@yamcodes yamcodes merged commit 63d6237 into main May 12, 2026
14 of 15 checks passed
@yamcodes yamcodes deleted the 924-is-the-cli-llm-friendly branch May 12, 2026 12:36
@arkenv-bot arkenv-bot Bot mentioned this pull request May 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

@arkenv/cli Issues or Pull Requests involving the ArkEnv CLI docs Improvements or additions to documentation www Improvements or additions to arkenv.js.org

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Is the CLI LLM friendly?

1 participant