Skip to content

[NYL-1012] Honour --json on the dashboard commands an agent drives - #130

Open
radenkovic wants to merge 1 commit into
mainfrom
NYL-1012-agent-json
Open

radenkovic wants to merge 1 commit into
mainfrom
NYL-1012-agent-json

Conversation

@radenkovic

@radenkovic radenkovic commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Why

NYL-1012: the upcoming Claude Code / Codex plugin (NYL-1013) drives nylas dashboard from an agent's shell, which needs to read results instead of scraping text. Several commands ignored --json.

This PR is the --json part of NYL-1012. Exit codes, non-blocking device login and the install path follow separately.

What changed

Command Before After
dashboard status text only report; {"logged_in": false, ...} when signed out (exit 0, like the text)
apps create text only application_id, region, environment, client_secret delivery
apps use text only {application_id, region}
apps apikeys create text only id, name, application_id, region, delivery
orgs switch text only {organization_id, organization_name, switched}
apps list, apikeys list, orgs list sentence when empty []
  • Secrets never appear in any format. Create commands report how a secret was delivered (method, delivered, file), never its value. The delivery logic moved to deliverAPIKey / deliverClientSecret in dashboard/output.go, so text and structured forms share it. The text wording is unchanged.
  • A structured run never prompts. It requires --delivery, --secret-delivery, an app ID for apps use and --org for orgs switch, because a prompt would write into the stream being parsed and hang an agent's tool call. Progress and partial-region warnings go to stderr.
  • isInteractive is now a variable so a test can simulate a terminal and prove that --json alone stops the prompt.
  • Docs: a "Structured output" section in docs/COMMANDS.md.

Testing

  • 12 new tests in dashboard/output_test.go. They cover: no secret in JSON, YAML or quiet output; the secret file has 0600 permissions; structured runs refuse instead of prompting; the status report; and OAuth orgs switch reporting the org that was chosen. I checked the prompt test with a mutation: removing the structured check makes it fail.
  • go test ./..., go test -race on the package, go vet, gofmt and golangci-lint (0 issues) pass locally.
  • I ran status --json, orgs list --json and apps list --json against a live production session. I didn't create apps or keys against production, so those paths are covered by unit tests only.
  • make vuln fails locally on Go standard-library advisories for the pinned go1.26.5 (fixed in 1.26.6). They are not related to this diff.

Known, not changed here

  • If --delivery activate fails, the CLI prints a warning, exits 0, and the new key is lost. JSON now shows "delivered": false, but the key still can't be recovered. A fallback to file delivery would fix it.
  • orgs list --json still prints "current": "✓". I left it alone so existing scripts don't break.

🤖 Generated with Claude Code

`nylas dashboard status`, `apps create|use`, `apps apikeys create` and
`orgs switch` printed text whatever the output flags said, and the list
commands printed a sentence instead of `[]` when empty. An agent or a
script could not read the result.

- Each now honours --json, --format yaml and --quiet through
  common.GetOutputWriter, with reports in dashboard/output.go.
- A secret is never written in any format: apps create and apikeys
  create report how it was delivered (method, delivered, file), not
  its value. Delivery moved into deliverAPIKey/deliverClientSecret so
  the text and structured forms share it.
- A structured run never prompts: it requires --delivery,
  --secret-delivery, an app ID for `apps use` and --org for
  `orgs switch`. Progress and partial-region warnings go to stderr.
- `status --json` reports logged_in false when signed out, exiting 0
  like the text form.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@qasim-nylas qasim-nylas left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

LGTM 👍

@qasim-nylas

Copy link
Copy Markdown
Collaborator

Code review findings

7 findings: 3 important, 2 nits, 2 pre-existing. They come from one review pass and were not re-checked, so please confirm each one before you act on it. go test ./internal/cli/dashboard/... passes on this branch.

🔴 Important

1. internal/cli/dashboard/keys.go:206: with --json/-q, a key that was created but not delivered is never reported
writeAPIKeyCreated returns delivery errors (temp file can't be written, or clipboard and file fallback both fail) before it calls Write. The text path prints the key ID before delivery, so only structured runs are affected. writeAppCreated (internal/cli/dashboard/apps.go:268) does the same: an app that was created but whose client secret wasn't delivered is never reported.

  • Scenario: nylas dashboard apps apikeys create --delivery file --json with TMPDIR unwritable → the key is created server-side, the CLI exits 1 with only failed to write file, and stdout is empty → the caller can't find or revoke the orphaned key, and the key value is lost.
  • Fix: still write the report, with the ID and a failed delivery entry, then return non-zero. At minimum, put the created ID in the error text.

2. internal/cli/dashboard/output.go:99: --delivery activate --json exits 0 when activation fails and throws away the only copy of the key
deliverAPIKey turns an activateAPIKey error into a delivered:false report with a nil error. The text path behaved the same before this PR. Structured output, though, is for callers that act on the exit code, and the key can't be retrieved later.

  • Scenario: keyring unavailable (headless Linux without Secret Service) → the command prints {"delivery":{"method":"activate","delivered":false,...}} and exits 0 → an agent treats that as success, and the key is unrecoverable.
  • Fix: fall back to a temp file the way clipboard delivery does, or return non-zero once the report is written.

3. internal/cli/dashboard/switch_org.go:45: orgs switch --json on an OAuth session still opens an interactive browser sign-in
This breaks the promise that "a structured run never prompts". The orgFlag == "" && (structured || !isInteractive()) refusal only runs after the if fromOAuth branch has returned, so the OAuth path never reaches it. With --org set, the structured OAuth path still always opens the browser.

  • Scenario: an agent signed in via nylas oauth login runs nylas dashboard orgs switch --json → a browser opens and the command blocks on the loopback callback until CreateLongContext times out.
  • Fix: in structured mode on an OAuth session, refuse before relogin and point the user to nylas oauth login to choose the org. Alternatively, apply the --org/non-interactive guard before the OAuth branch.

🟡 Nit

4. internal/cli/dashboard/switch_org.go:54: structured OAuth switch always reports switched:true and leaves out organization_name
The re-sign-in may land on the org the session was already in. The non-OAuth path reports switched:false in that case.

  • Scenario: session on org_1, user picks org_1 again → {"organization_id":"org_1","switched":true}.
  • Fix: compare the chosen org with the session org before relogin to set Switched, and fill OrganizationName when it's available.

5. internal/cli/integration/dashboard_test.go: no integration coverage for the new structured output
Structured output was added to 7 dashboard commands with unit tests only. Per the project rules in CLAUDE.md, a new feature needs unit tests, integration tests and docs.

  • Fix: add integration tests for at least status --json, apps list --json and orgs list --json, or note why they're exempt.

⚪ Pre-existing (more visible after this PR)

6. internal/cli/dashboard/apps.go:31: apps list -q / orgs list -q print nothing
appRow and orgRow (switch_org.go:236) have no ID field and no QuietField(), so extractQuietField returns "" for every row. The PR now skips the "No applications found" text in structured mode, so quiet output is empty whether or not apps exist.

  • Fix: add QuietField() returning ApplicationID / PublicID.

7. internal/cli/dashboard/apps.go:31: --format yaml keys don't match --json on apps/apikeys/orgs list
appRow, apiKeyRow (keys.go:34) and orgRow carry only json tags, so yaml.v3 falls back to lowercased Go field names (applicationid vs application_id). The new report types in this PR already carry yaml tags.

  • Fix: add yaml tags that match the json tags on these three row types.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants