[jordienr]

Compatibility clarification

Advisors stays visible, discoverable, documented, and usable alongside Issues. Deprecation is planned for a future release; the informational notices do not announce removal or a removal date. Existing contracts and permissions remain supported.

Verified correction at 089e9b262

db advisors remains listed in CLI help; flags, output and exit behavior are unchanged. The stderr notice and reference text now describe planned future deprecation. Independent QA passed all 57 Advisors integration tests with retries disabled and shuffle seed 1114; formatting/lint and worker help checks passed. Earlier screenshots below remain evidence for unchanged Issues output.

Latest-head CI passes, including CLI integration and end-to-end suites. Conditional duplicate, benchmark, maintenance, and preview jobs are skipped.

Problem

Studio is moving from Advisors to Issues Inbox, while the CLI still exposes supabase db advisors. CLI users also need remote health checks alongside security and performance findings.

What this adds

• supabase issues combines security, performance, and remote health checks, grouping affected resources under each issue.
• Readable terminal output uses the shared CLI table renderer, wraps long titles, and falls back to stacked label/value fields in narrow terminals, matching logs.
• Machine output stays available through --output-format json and stream-json, including affected resources, evidence, and remediation links. Detected coding agents retain the CLI's JSON default.
• Filtering and exit control use --type, minimum --severity, and --fail-on. Defaults are all, info, and none respectively.
• Explicit coverage distinguishes completed checks from unavailable checks. Empty filtered results do not imply unavailable checks passed; unavailable remote checks exit nonzero.
• Backwards compatibility: db advisors retains its flags, defaults, output, and exit behavior, with an informational notice on stderr about planned future deprecation. Both commands reuse existing Advisors endpoints and check modules.
• CLI reference docs cover the command, defaults, terminal output, and machine modes.

Local and direct database targets keep SQL checks and report health as unavailable; explicitly requesting local health is rejected. Use --output-format, not the older -o flag. Issue IDs identify project-scoped checks, not persistent incidents; lifecycle actions and banned-IP signals are outside this PR.

Command and flags reference

supabase issues [--remote[=<ref|branch|url>]] \
  [--type all|security|performance|health] \
  [--severity info|warning|critical] \
  [--fail-on none|info|warning|critical] \
  [--output-format text|json|stream-json]

Issues flags

These are the check-selection, filtering, and exit-control flags exposed by the new command.

Flag	Accepted values	Default	Behavior
--type <value>	all, security, performance, health	all	Selects which checks run. all requests all three categories. Health requires a hosted project target.
--severity <value>	info, warning, critical	info	Minimum grouped issue severity to display: info includes everything, warning includes warning and critical issues, and critical includes only critical issues. A group's severity is its highest affected-resource severity; matching groups retain all affected resources and evidence.
--fail-on <value>	none, info, warning, critical	none	Exit with status 1 when a displayed issue meets or exceeds this threshold. none disables failure based on findings; it does not suppress command errors or unavailable remote checks.

Severities map from the underlying Advisors levels: INFO → info, WARN → warning, ERROR → critical. --severity filters the results before --fail-on is evaluated. Neither flag changes which API checks are requested.

Target selection

The command reuses the existing CLI target flags; these are not new global flags.

Form	Target and behavior
No target flag	Inspect the local database.
--remote	Inspect the linked hosted project.
--remote=<project-ref>	Inspect the specified hosted project.
--remote=<branch>	Resolve and inspect the specified project branch.
--remote=<postgresql-url>	Connect directly to that database for SQL checks. A direct database URL does not enable hosted health checks.

Use = when supplying a remote target, for example --remote=erppftcfodkcyoftaqvb, rather than --remote erppftcfodkcyoftaqvb. Local and direct-URL security/performance checks run in a transaction that is always rolled back. With those targets, --type all reports health as unavailable; explicit --type health fails with guidance to use a hosted project.

The shared, hidden compatibility flags remain accepted but are deprecated for removal in CLI v4: --local (omit the target flag), --linked (use --remote), --project-ref <ref> (use --remote=<ref>), and --db-url <url> (use --remote=<url>).

Shared output and execution flags

These existing global flags apply to issues:

Flag	Values / default	Behavior
--output-format <value>	text, json, stream-json; normally text	text prints a table or narrow-terminal stacked fields, followed by coverage. json includes full issues and checks. stream-json emits newline-delimited JSON events, with the structured result in the result event.
--agent <value>	auto, yes, no; default auto	Controls the CLI's existing agent detection. Detected agents use JSON by default. Use --agent no to exercise normal human defaults; an explicit output format selects the requested format.
--profile <name>	Existing CLI profile selection	Selects the profile used to connect to the Supabase API.
--workdir <path>	Normally searches upward from the current directory	Uses the specified directory containing supabase/ exactly, without ancestor search. This determines the local project context and linked project.
--debug	Off unless enabled	Writes debug logs to stderr.
--help, -h	No value	Shows command usage, flags, and conditional token permissions.

Other inherited global options remain listed in supabase issues --help; this PR does not change them. Although inherited help lists --output / -o, this command rejects that legacy output flag and directs callers to --output-format.

Exit behavior

Condition	Result
Checks complete and no displayed issue reaches --fail-on	Exit 0. Findings alone do not fail the default --fail-on none run.
A displayed issue reaches the configured --fail-on threshold	Exit 1.
A hosted check is reported unavailable	Coverage includes the reason; exit 1, even with --fail-on none.
Local/direct-URL --type all cannot run health	Health is marked unavailable; this expected limitation alone does not force exit 1. The findings threshold still applies.
Invalid arguments, unsupported explicit health target, authentication, or execution failure	Nonzero exit; not a clean assessment.

For example, --severity critical --fail-on warning fails only if a critical issue is displayed. Warning issues have already been filtered out. An empty result means no issues match the filter, not that every check completed successfully.

Examples

supabase issues
supabase issues --remote --type security --severity warning
supabase issues --remote=erppftcfodkcyoftaqvb --type health --output-format json
supabase issues --remote=erppftcfodkcyoftaqvb --output-format stream-json
supabase issues --remote --severity info --fail-on warning
supabase issues --remote --agent no --output-format text

For scoped access tokens, hosted checks require advisors_read. Project selection may additionally require projects_read; branch resolution may require branching_development_read or branching_production_read. project_admin_read is optional for this command, as reported by --help.

Earlier verification

Check	What was verified	Result
Live Mockamaster regression	24 cases covering Issues, legacy Advisors, validation, JSON/stream-JSON, severity filtering, and fail-on exits	Passed; 16 Issues cases, 4 legacy Advisors cases, and 4 validation/error cases
Human-readable output	Actual compiled CLI at 80/120 columns; latest head at 40 columns	Tables and stacked fields render correctly; security warnings return 6 grouped issues and complete coverage, exit 0
Latest-head focused tests	14 renderer/logs unit tests and 57 handler integration tests, retries disabled, shuffled seed 1113	Passed
Regression sensitivity	Deliberately removed stacked fallback, warning wrapping, and summary wrapping	Tests caught each mutation; restored source passed
Static checks and build	Types, changed-file lint/formatting, compiled binary	Passed
Latest-head CI	Code quality, unit/integration suites, CLI and stack E2E, macOS/Windows checks, PR lint, and JS/TS CodeQL	Passed on b2c21a6b7

Mockamaster has no critical, mixed-severity, or unavailable checks. Those cases are covered by fixtures, not claimed as live coverage. Conditional/draft CI jobs are skipped; the separate CodeQL comparison is neutral due to the base branch's obsolete Go configuration.

Earlier verification on head 681ec2d

• 78 handler/integration tests and 41 renderer/logs unit tests passed with retries disabled and shuffled seed 1112; types, changed-file lint/formatting, and binary build passed.
• Tests caught deliberate mutations to text/machine routing, unavailable coverage, and 120-column width handling. Source was restored and clean tests passed.
• All 34 full CI jobs passed, alongside PR lint and JS/TS CodeQL: CI run.

How to test

Using a build of this branch and an authenticated project:

supabase issues --remote=<project-ref> --agent no
supabase issues --remote=<project-ref> --agent no --type security --severity warning
supabase issues --remote=<project-ref> --type health --output-format json
supabase issues --remote=<project-ref> --output-format stream-json
supabase issues --remote=<project-ref> --severity warning --fail-on warning
supabase db advisors --remote=<project-ref>

Expect readable tables in a normal terminal and stacked fields at 40 columns. JSON modes retain full findings and coverage. --fail-on warning exits nonzero when matching warning-or-higher findings exist. The legacy command preserves its response and adds its informational future-deprecation notice on stderr. --agent no explicitly selects human defaults when testing from a coding-agent environment.

Screenshots

Actual compiled CLI against Mockamaster. The 80-column screenshot records head 681ec2d; output at 80/120 columns was verified unchanged by the narrow-terminal follow-up.

80-column table

Additional live screenshots: 120-column table, security warnings, and empty health results

Captured from head 681ec2d against Mockamaster in Jordi - Team, using the actual compiled CLI in a read-only localhost browser terminal. Output was not reconstructed or projected through jq, and no project resources changed. PTY width was set after browser initialization; the browser canvas may be wider than the configured PTY.

Default issues, 120 columns

All 11 grouped issues, complete security/performance/health coverage, exit 0.

Security warnings, 80 columns

--type security --severity warning: six warning issues and 11 affected findings, wrapped titles, complete coverage, exit 0.

Empty health results, 120 columns

--type health: no matching issues, complete health coverage, exit 0.

40-column stacked output

Fresh run of b2c21a6b7 against Mockamaster: six security-warning issues, complete security coverage, exit 0. Two screenshots show the beginning and end of the same run. The PTY is 40 columns; shared CLI update notices retain their existing behavior.

Linked issue: CLI-2888.