Fix UX/DX audit findings across the CLI surface#58
Merged
Conversation
Address the prioritized findings from the UX/DX audit:
High
- Onboarding no longer hangs: a non-interactive `aai onboard` session
refuses to start a browser sign-in (which would block ~2min on a
callback that can't arrive) and fails fast with actionable guidance.
- `aai transcripts get --json` now emits the full transcript payload,
identical to `aai transcribe --json`, so a fetched transcript
round-trips for scripting.
- Exit codes are consistent: deploy usage errors and the voice-agent
rejected-connection error use the canonical UsageError (2) /
NotAuthenticated (4) codes. Documented the exit-code contract in
errors.py and the README, plus a JSON-output schema table.
Medium
- doctor flags an unusable OS keyring and recommends ASSEMBLYAI_API_KEY
(instead of a dead-end browser login), and suggests a next step on
success.
- `aai login --api-key` now warns that account self-service needs a
browser login.
- The env-mismatch warning carries remediation and is emitted as a
structured {"warning": …} object in --json mode.
- transcripts/sessions timestamps normalized to UTC and labelled;
empty-state messages for transcripts/sessions/keys list.
- `--quiet` now also suppresses the spinner.
- Reworded the misleading `--prompt` help and split the dense
transcribe/stream docstrings so help renders cleanly.
Low
- `-j` short alias for `--json`; `usage --include-zero` (keeps `--all`);
concrete `sessions get` example id; unified file-not-found wording;
added remediation to AMS/LLM-gateway errors and the keys no-project
error.
README documents the flat account command layout and leads Quick Start
with `aai onboard`. Tests + snapshots updated; full gate green.
https://claude.ai/code/session_014YFntb8MvWVTJNoS4dVpoP
Add a "Writing tests that pass the diff gates" subsection documenting the friction points hit this session: boolean literals/defaults surviving the mutation gate unless a test asserts the behavioral difference; help text being pinned by snapshots (not unit asserts); CliRunner merging stderr into output out of call order; and --json/-j being a per-command flag, not a root flag. https://claude.ai/code/session_014YFntb8MvWVTJNoS4dVpoP
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Address the prioritized findings from the UX/DX audit:
High
aai onboardsessionrefuses to start a browser sign-in (which would block ~2min on a
callback that can't arrive) and fails fast with actionable guidance.
aai transcripts get --jsonnow emits the full transcript payload,identical to
aai transcribe --json, so a fetched transcriptround-trips for scripting.
rejected-connection error use the canonical UsageError (2) /
NotAuthenticated (4) codes. Documented the exit-code contract in
errors.py and the README, plus a JSON-output schema table.
Medium
(instead of a dead-end browser login), and suggests a next step on
success.
aai login --api-keynow warns that account self-service needs abrowser login.
structured {"warning": …} object in --json mode.
empty-state messages for transcripts/sessions/keys list.
--quietnow also suppresses the spinner.--prompthelp and split the densetranscribe/stream docstrings so help renders cleanly.
Low
-jshort alias for--json;usage --include-zero(keeps--all);concrete
sessions getexample id; unified file-not-found wording;added remediation to AMS/LLM-gateway errors and the keys no-project
error.
README documents the flat account command layout and leads Quick Start
with
aai onboard. Tests + snapshots updated; full gate green.https://claude.ai/code/session_014YFntb8MvWVTJNoS4dVpoP