[AX] Audit CLI surface for agent-safe vs human-only commands and modes

[manojbajaj95]

Summary

authsome is intended to be used by agents to manage credentials, but the current CLI surface still mixes agent-safe primitives with workflows that assume a human terminal, GUI, browser, OS-auth dialog, or manual operator judgment.

This issue tracks a full audit of the CLI surface so the primary command path is clearly agent-first:

• machine-safe commands stay top-level and are easy to discover
• human-only or operator-only workflows are moved behind an explicit subgroup, advanced mode, or other clear boundary
• command modes that are agent-safe in one configuration but human-only in another are classified at the flag/submode level, not just by top-level command name

The goal is not to delete useful human tooling. The goal is to stop mixing it into the default surface that agents are expected to rely on.

Problem statement

Today, several commands or command modes still assume human interaction, local desktop affordances, or security ceremonies that are unsuitable for unattended agent execution.

Examples:

• ui always opens a browser dashboard
• login often starts an interactive session that completes later and may open a browser
• scan is agent-safe in report-only / --import form, but plain scan may prompt for confirmation
• register may prompt for confirmation
• get --show-secret triggers OS-level authentication via require_os_auth(...)
• daemon, doctor, and log are primarily operator/debug surfaces rather than core agent primitives
• profile management may be useful, but is not part of the typical agent credential loop

This creates two kinds of confusion:

1. Agents cannot tell from authsome --help which commands are safe to automate.
2. Some commands are broadly useful, but only certain flags or modes are agent-safe.

Scope of the audit

This audit should classify both:

• top-level commands
• human-only submodes / flags on otherwise useful commands

That means the review should explicitly consider command variants such as:

• get vs get --show-secret
• scan --json / scan --import vs plain scan
• login --json / future wait-or-polling modes vs default interactive login behavior
• daemon subcommands as a group
• profile subcommands as a group

Proposed classification model

Each command or mode should be assigned one of these verdicts:

• Keep top-level: safe and useful for agents by default
• Keep but gate human-only modes: top-level command stays, but certain flags/submodes move behind an explicit boundary
• Move under advanced, dev, or human subgroup: still supported, but not part of the primary agent-facing surface
• Deprecate / remove: not justified in the long-term CLI surface

Initial command review

Command / mode	Agent-useful?	Initial verdict
run	Core primitive	Keep top-level
list	Discovery	Keep top-level
get	Credential/metadata read	Keep top-level
get --show-secret	Sensitive plaintext reveal with OS auth	Keep but gate human-only mode
scan --json	Read-only drift report	Keep top-level
scan --import	Explicit apply/import path	Keep top-level
plain scan	Confirmation-driven human workflow	Keep but gate or harden
inspect	Config introspection	Keep top-level
whoami	Identity context	Keep top-level
set-default	Connection management	Keep top-level
init	One-time setup	Keep top-level
login	Required, but currently interactive/session-based	Keep top-level, continue AX hardening
logout	Occasionally useful cleanup	Keep, possibly de-emphasize
revoke	Credential rotation	Keep top-level
export	Handoff / interop	Keep top-level
register	Provider onboarding/operator task	Move behind explicit advanced/dev boundary
remove	Provider management/operator task	Move behind explicit advanced/dev boundary
profile	Identity management	Evaluate as advanced/human-oriented
daemon	Process management/debugging	Move behind explicit advanced/dev boundary
doctor	Health-check/debugging	Move behind explicit advanced/dev boundary
log	Audit/debug viewer	Move behind explicit advanced/dev boundary
ui	Browser dashboard	Remove from primary agent path entirely

Desired end state

An agent looking at authsome --help should immediately understand the supported automation path without having to reverse-engineer which commands open browsers, wait for prompts, trigger OS-auth, or require a human operator.

That likely means:

• top-level help is machine-oriented and compact
• human/operator commands are clearly grouped elsewhere
• commands that remain top-level are agent-safe by default
• human-only modes on top-level commands are explicit and clearly documented

Acceptance criteria

• Every top-level command is explicitly classified as: keep top-level, gate a human-only mode, move, or remove
• Human-only flags/submodes on otherwise useful commands are explicitly audited and classified
• Commands that require browser interaction, OS-auth, local GUI affordances, or operator judgment are no longer mixed into the default agent-facing path without clear labeling or grouping
• authsome --help makes the primary agent-safe workflow obvious
• Kept top-level commands have validated and documented --json behavior
• The docs describe the CLI as agent-first and distinguish agent-safe vs human/operator surfaces
• No regression in existing test coverage

Notes

This issue is an umbrella/product-direction issue. Concrete follow-up issues can still exist for specific command improvements such as login waiting/polling, JSON output fixes, non-interactive confirmation behavior, or secret-reveal gating.

[ankitranjan7]

Split the umbrella into concrete follow-up issues:\n\n- #309\n- #310\n- #311\n- #312\n- #313