tarunsachdeva shared in

Improve CLI for Agent Compatibility and Safety

Agent

OpenCode

Model

GPT-5.4

Started

Mar 25, 3:28 PM

Messages521

Downloads103

Summary

Can you read this tweet: https://x.com/ericzakariasson/status/2036762680401223946

Can you take a look at our CLI and based on some of the recommendations in the article, make some recommendations on how to harden our CLI to be more agent friendly.

I couldn’t read the X page directly, but I recovered the linked article from a public mirror. The title was Building CLIs for agents, and the main themes were: make commands fully non-interactive, make --help locally discoverable and example-heavy, accept stdin, fail fast with actionable errors, keep mutating commands idempotent, add --dry-run, use predictable naming, and return structured output.

What’s Already Good

share, list, setup, and remove skills already have solid JSON envelopes with ok/data/error, which is a strong base for agent usage: cli/src/commands/share.ts:721, cli/src/commands/list.ts:197, cli/src/commands/setup.ts:710, cli/src/commands/remove-skills.ts:383
share already has good headless-discovery ideas: explicit selectors, env hints, and --list fallback: docs/cli.md:111
Auth is scriptable via --key and TRACES_API_KEY, not just browser login: docs/cli.md:83
Setup/remove flows are mostly idempotent, especially for skills and git hook marker insertion/removal: cli/src/commands/setup.ts:644, cli/src/commands/hooks.ts:127

Biggest Hardening Gaps

Unknown flags are silently ignored, which is the biggest agent footgun here: cli/src/commands/share-options.ts:3, cli/src/commands/list-options.ts:13, cli/src/commands/setup-options.ts:3, cli/src/commands/remove-skills-options.ts:3
Help is mostly top-level only; most subcommands do not have real --help, and examples are sparse: cli/src/index.ts:150, cli/src/commands/setup.ts:400
JSON output is inconsistent across automation-facing commands like status, doctor, whoami, namespace, and transfer: cli/src/commands/status.ts:66, cli/src/commands/doctor.ts:319, cli/src/commands/whoami.ts:20, cli/src/commands/namespace.ts:159, cli/src/commands/transfer.ts:5
Destructive commands don’t have --dry-run, and confirmation behavior is inconsistent: cli/src/commands/reset.ts:58, cli/src/commands/remove-skills.ts:280, cli/src/commands/hooks.ts:201, cli/src/index.ts:265
There’s basically no stdin-based composition path for IDs/selectors; stdin is used for prompts, not machine input: cli/src/commands/reset.ts:44

Recommended Order

Make argument parsing strict and fail-fast. Unknown flags should return INVALID_ARGUMENTS with a suggestion like “did you mean --cwd?”. Right now an agent typo can silently do the wrong thing.
Add real traces <command> --help for every nontrivial command, with 2–4 concrete examples each. setup --help is the right direction; apply it everywhere.
Add --json to every automation-relevant command and standardize on one contract: payload on stdout, diagnostics on stderr, stable ok/data/error.code/error.message.
Add a global --non-interactive mode. In that mode, any prompt should become a structured error telling the caller which flags are required instead.
Add --dry-run to all mutating/destructive commands: reset, remove skills, remove git, setup git, transfer, and uninstall.
Add stdin support for common pipelines, e.g. --trace-id -, --to -, or a shared --input json mode.
Normalize naming and aliases. share --cwd vs list --dir is harder for agents to infer than it needs to be; same with --key vs a clearer alias like --api-key.
Publish a small exit-code contract and use it everywhere. You already use 2 for invalid args in some commands; make that universal.

If I were prioritizing purely for agent-friendliness, I’d do these first:

strict flag parsing
per-command help with examples
JSON everywhere

If you want, I can turn this into a concrete implementation plan for cli/ with command-by-command changes and suggested output schemas.

argument parsing strict < what does this mean? give example

Strict argument parsing means: if the caller passes anything invalid, the CLI errors immediately instead of silently ignoring it.

Right now some of your parsers are permissive. For example, cli/src/commands/share-options.ts:3 and cli/src/commands/list-options.ts:13 skip unknown flags, and you even test for that in cli/src/commands/share-options.test.ts:93.

Concrete example:

Current behavior:

What happens now:

--jsno is ignored
command still runs
agent thinks it asked for machine-readable output, but gets human text instead

Strict behavior:

Why this matters for agents:

agents typo flags
agents infer flags that “should exist”
silent ignore turns a clear mistake into wrong behavior

A few more examples of “strict”:

Unknown flag

permissive: ignores typo, may open an interactive confirm prompt and hang automation
strict: Unknown option --yees. Did you mean --yes?
Missing value

strict: Missing value for --trace-id
Invalid enum

strict: Invalid value for --visibility. Use public, direct, or private.
Extra positional args

strict: Unexpected argument extra

You already do some strict validation later in cli/src/commands/share.ts:467 for things like invalid --visibility or conflicting selectors. My recommendation was to push that strictness down into the parsing layer too, especially for unknown flags and missing values.

If you want, I can sketch what a stricter parser API would look like for share, list, and remove skills.

okay i like all your recommendations. 6 and 7 might break existsing clients so backcompat is required.

Yep — I’d treat 6 and 7 as additive, not replacements.

stdin support: keep current flags exactly as-is, and only read stdin when the caller opts in explicitly
Good backcompat pattern:
- traces share --trace-id - -> read one trace id from stdin
- traces transfer --to team --trace-id - -> read id from stdin
- or --from-stdin / --input json as new opt-in flags
Avoid auto-reading piped stdin just because input exists; that’s what usually breaks existing scripts
Naming normalization: add aliases, keep current names canonical internally
Good backcompat pattern:
- keep --cwd, add --dir as alias for share
- keep --dir, add --cwd as alias for list
- keep --key, add --api-key and maybe --token as aliases
Parse all aliases into the same internal field, and keep existing docs/examples working

A safe rollout would be:

Add aliases and opt-in stdin paths
Keep old flags fully supported
Show canonical names in --help
Optionally add soft deprecation notices later, but only in human mode and not in --json

Example of strict + backcompat together:

This should work because --api-key is an alias for --key.

But this should fail:

with:

That gives you stricter agent behavior without breaking existing clients.

If you want, I can turn the recommendations into:

a compatibility-safe implementation plan, or
the actual CLI changes, starting with the lowest-risk ones.

Do 1

Lets create a worktree and do this work in there

Set this up in a clean worktree off main so it stays isolated from the dirty current branch.

Worktree: /Users/tarunsachdeva/code/traces-worktrees/feat-cli-agent-hardening
Branch: feat/cli-agent-hardening
Bootstrapped there with bun install

I wrote the compatibility-safe implementation plan in docs/projects/cli-agent-hardening.md and linked it from docs/README.md.

The plan covers:

strict parsing without silent flag ignores
per-command --help with examples
broader --json coverage and exit-code cleanup
--dry-run and explicit non-interactive behavior for mutating commands
additive stdin support and aliases only, with backcompat preserved
a phased rollout and test plan

Natural next steps:

Start Phase 0-1 in this worktree by building the shared strict parser utility
Review the plan doc together and adjust phase ordering before implementation

Let's start

Started the first hardening slice in the worktree at /Users/tarunsachdeva/code/traces-worktrees/feat-cli-agent-hardening.

Added a shared strict parser in cli/src/commands/strict-parser.ts so commands can fail fast on unknown flags, missing values, and extra positional args with actionable usage text
Migrated share, list, setup, remove skills, and transfer to use strict parsing through cli/src/commands/share-options.ts, cli/src/commands/list-options.ts, cli/src/commands/setup-options.ts, cli/src/commands/remove-skills-options.ts, and new cli/src/commands/transfer-options.ts
Wired parse failures into the CLI entrypoints in cli/src/index.ts and cli/src/share-entry.ts, including JSON-shaped INVALID_ARGUMENTS errors when --json is present
Kept backcompat for existing valid invocations; this slice only removes silent-ignore behavior for invalid ones
Added/updated parser tests in cli/src/commands/share-options.test.ts, cli/src/commands/list-options.test.ts, cli/src/commands/setup-options.test.ts, cli/src/commands/remove-skills-options.test.ts, and cli/src/commands/transfer-options.test.ts

Verified with:

bun test src/commands/share-options.test.ts src/commands/list-options.test.ts src/commands/setup-options.test.ts src/commands/remove-skills-options.test.ts src/commands/transfer-options.test.ts
bun test src/commands/share.test.ts src/commands/list.test.ts src/commands/setup.test.ts src/commands/remove-skills.test.ts
bunx tsc --noEmit

Natural next steps:

Add per-command --help and examples for the commands we just hardened
Extend --json to status, doctor, whoami, namespace, and transfer
Add --dry-run / non-interactive hardening for destructive commands

Can you create a PR and share this trace to the PR

Created the PR for the first CLI hardening slice and attached the trace to it.

PR: https://github.com/market-dot-dev/traces/pull/588
Trace: https://traces.com/s/jn78srhfgeqd1mmdsxcpb2vd4x83j58y
I posted the trace link on the PR as a comment and included the implementation summary/testing in the PR body
Branch: feat/cli-agent-hardening
Commit: f26078ee (fix: fail fast on invalid CLI option parsing)

I also verified the slice with:

bun test src/commands/share-options.test.ts src/commands/list-options.test.ts src/commands/setup-options.test.ts src/commands/remove-skills-options.test.ts src/commands/transfer-options.test.ts
bun test src/commands/share.test.ts src/commands/list.test.ts src/commands/setup.test.ts src/commands/remove-skills.test.ts
bunx tsc --noEmit

If you want, I can start the next slice in this branch: per-command --help and examples.

Please update the docs pages to reflect all these changes

Updated the docs to match the strict parsing slice and the current CLI surface.

docs/cli.md
- added transfer to the command list
- documented global --key auth usage
- added an Argument Validation and Automation section covering fail-fast parsing, exit code 2, and JSON INVALID_ARGUMENTS errors
- fixed setup docs to use space-separated --agent values
- documented setup git / remove git as available
- added a dedicated transfer section
docs/projects/cli-agent-hardening.md
- added a Current Status section describing what’s already landed in this branch
- marked the first Phase 1 slice as complete-in-branch
- clarified what still remains

Notably, I also corrected a couple of stale docs claims:

docs/cli.md no longer says setup git / remove git are “reserved”
docs/cli.md no longer implies comma-separated --agent values for setup

These doc changes are local in the worktree right now and not yet committed/pushed to the PR. If you want, I can add them to the existing PR next.

please push to the PR yes

Pushed the docs update to the existing PR.

PR: https://github.com/market-dot-dev/traces/pull/588
New commit: ced87b03 — docs: update CLI hardening guidance

I updated:

docs/cli.md
docs/projects/cli-agent-hardening.md

This adds the new strict parsing behavior, auth notes, transfer, git hook commands, and marks the first hardening slice as complete in the project doc. No tests were run since this was docs-only.

no i don't need to add a project called cli-agent-hardening, aren't all the changes in here already, don't pollute the repo

Yep — agreed. I removed the extra planning doc and pushed the cleanup to the PR.

Removed docs/projects/cli-agent-hardening.md
Removed its index entry from docs/README.md
Kept the actual shipped behavior documented in docs/cli.md

Pushed to the same PR:

PR: https://github.com/market-dot-dev/traces/pull/588
Cleanup commit: 6e60ce64 — docs: remove extra CLI hardening plan

So the repo is back to just the real CLI docs, without the extra project page.

rebase against main, this PR has conflicts

Rebased the branch onto origin/main and force-pushed the PR branch.

Branch now sits on top of 23e8c7e3 (origin/main)
Updated PR branch: feat/cli-agent-hardening
Force-pushed with --force-with-lease, so the PR should be conflict-free now
I resolved the rebase conflict in docs/cli.md by keeping both sets of docs updates: the newer auth/share-discovery notes from main and this PR’s strict parsing / transfer / git hook docs
Latest branch tip: 1bee48ac (docs: remove extra CLI hardening plan)

I didn’t rerun tests since the only rebase conflict was in docs.

is this 588

Yes — this is PR #588.

URL: https://github.com/market-dot-dev/traces/pull/588

I rebased and force-pushed that PR branch.