tryagent

Production human-in-the-loop for AI agents — one CLI with one story: a guided flow to get governed, deterministic primitives for CI, and full parity with the web dashboard.

npx tryagent               # guided flow: login → setup → walk your agents → publish
npx tryagent status        # where you stand: setup, auth, coverage, autonomy, drift
npx tryagent agents        # your decision points: list, walk, show
npx tryagent scan          # deterministic, read-only findings for CI

No install step: npx runs the published package directly (and reuses a local install when one exists).

Paths: every command that takes a [path] treats an explicit path as the project root — tryagent init examples/refund-bot sets up exactly that directory, so monorepo sub-projects work. Without a path, commands discover the root from the current directory (walking up to .git).

The guided flow

Bare npx tryagent always does the next right thing, and asks before each step:

1. Sign in — browser sign-in; signup happens on the same page.
2. Set up the repo — tryagent.json, a repo API key in .env (gitignored), and the repository intelligence index.
3. Walk your agents — for every uncovered decision point: see the call site and its evidence, get a drafted rubric, pick an autonomy mode, and wire the guard (below).
4. Publish — push repo rubric files to the platform.
5. Status — a summary of where you stand.

Every step is also a standalone command (login, init, agents walk, rubrics push, status), so you can enter the flow anywhere. Non-TTY and --yes/--json invocations skip the guidance and keep the exact batch semantics CI scripts depend on.

Walk your agents: npx tryagent agents

agents is the decision-point surface — an agent is identified by the agentId committed in your code.

npx tryagent agents list          # coverage, autonomy mode, graduation readiness
npx tryagent agents walk          # govern uncovered calls one at a time
npx tryagent agents show <agentId>

In a terminal every choice is arrow-key navigable (↑/↓ or j/k, Enter; digits jump). When several decision points are uncovered, the walk opens with a picker so you can address issues in any order, sweep the rest in one pass, or finish early and apply what's staged.

agents walk shows each uncovered LLM call with its discovered decision surface, drafts a rubric remotely (redacted source context, sent only with your consent), and asks you to pick an autonomy mode:

• required — always pause and wait for a human decision
• reviewed — execute the automatic choice and record it for later review
• sampled — execute automatically, but pause a configured percentage
• autonomous — execute automatically without routine human review

The walk recommends a starting mode deterministically from the decision surface — a call that can reach payments, email, database writes, or tools starts at required; a pure generation call starts at reviewed. The platform graduates decision points up the ladder later, from real override data; the CLI never invents thresholds. Drafts can be accepted, edited in $VISUAL/$EDITOR, regenerated, or skipped; all accepted changes (rubric files, exact guard() wiring, SDK manifest edits) are validated and applied together after one confirmation. --yes skips only that final confirmation.

Publishing the committed rubric files is a separate, reviewable step:

npx tryagent rubrics diff    # compare repo files to latest platform versions
npx tryagent rubrics push    # publish changed repo files as new versions

CI primitives

npx tryagent scan [path]

Deterministic codebase scan — no API key required, safe for CI:

• LLM call sites (Anthropic, OpenAI, Vercel AI SDK, LangChain) with two checks per call: is the output schema-validated (Zod, structured outputs), and is the call registered with TryAgent (a guard()/escalation in the file)? Unregistered calls get a proposed agentId.
• Unguarded side effects (payments, email, SMS, destructive DB/fs, shell, HTTP writes, storage deletes) — reported only on the agent surface (files that define a workflow/tool or call an LLM). Cross-file: a side effect in a helper file is flagged when an ungoverned agent file reaches it through imports; an approval anywhere on the path gates it.
• Repo rubric coverage: committed agentIds need a matching .tryagent/rubrics/<agentId>.json so thresholds and modes are reviewed in PRs. Logged-in scans also report platform publish state.

On a terminal, a scan that finds uncovered decision points ends with an arrow-key prompt offering to govern them right away (it hands off to agents walk); declining exits with the normal scan result. Piped and CI runs never prompt and stay deterministic.

Flags: --json for tooling, --fail-on high|medium|any to gate CI, --fail-on-unguarded to gate specifically on unguarded side effects, and --interactive to skip the question and go straight into the walk.

npx tryagent review — governance diff gate

Flags governance regressions in a unified diff and exits 1 on blockers: removed approvals, orphaned agentIds, new ungoverned capability, prompt changes, and stale rubrics (logged in only).

npx tryagent review --base origin/main --markdown   # PR-comment markdown
git diff -U0 | npx tryagent review                  # or pipe any unified diff

npx tryagent index [--check] — repository intelligence

Indexes packages, agents, LLM calls, prompts, tests, security boundaries, and ownership into .tryagent/ (canonical source: .tryagent/index.json), and maintains the managed guidance block in AGENTS.md/CLAUDE.md. Output is deterministic and safe to commit; --check exits non-zero on drift.

Skills: npx tryagent skills

The repo workflows rendered to .tryagent/skills/*/SKILL.md for coding assistants (code-review, ai-safety, prompt-editing, llm-upgrade, security):

npx tryagent skills list
npx tryagent skills disable llm-upgrade   # persisted in tryagent.json
npx tryagent skills sync                  # re-render from configuration

index and index --check respect the configuration, so commit tryagent.json and .tryagent/skills/ together.

Setup commands

npx tryagent login

One browser sign-in (signup included) — no flags or env vars needed. --org <id> scopes multi-org accounts; --api-key pastes a key instead. Credentials live in ~/.config/tryagent/config.json with mode 600.

npx tryagent init

Sets up the current repo: resolves an API key (or mints one from your logged-in session), validates it, writes tryagent.json, puts the key in .env, ensures .env is gitignored, and builds the repository intelligence index. Non-interactive: npx tryagent init -y --api-key <key>.

Configuration commands (auth required)

Everything you can configure on the web dashboard works from the CLI after npx tryagent login — configuration always rides your user session and RBAC, never the repo API key (keys only authenticate the escalations data plane). Every command supports --json. These live under npx tryagent help --all to keep the core help focused on the journey.

npx tryagent policies list
npx tryagent policies create --key payments.refund --name "Refund approval" --sla 2h
npx tryagent policies update payments.refund --queue Finance
npx tryagent keys create --name ci --accept-legal
npx tryagent orgs
npx tryagent api GET /schedules            # full-parity escape hatch, like `gh api`
npx tryagent api POST /groups --data '{"name":"Payments reviewers"}'

Exit codes and deprecations

0 success · 1 findings, gate failure, or command error · 2 usage error (unknown command, flag, or flag value).

tryagent generate and tryagent check still work but are deprecated: generate forwards to agents walk (identical --yes --json batch behavior), check forwards to scan.

Requirements

Node.js >= 20.17.