Skip to content

Add --json output flag to read commands #60

@ewega

Description

@ewega

Problem

All CLI output is human-formatted (emoji, Unicode box-drawing, banners). There is no machine-readable output mode. This blocks two scenarios:

  1. Agent consumption — coding agents (Copilot CLI agent, Claude, etc.) cannot reliably parse CLI output to take follow-up actions
  2. Scripting — users who want to pipe gh devlake output into jq, dashboards, or automation scripts must screen-scrape

The Playwright CLI demonstrates the pattern: CLI commands return structured snapshots to stdout that agents consume directly. For gh-devlake, the equivalent is structured JSON from read commands.

Proposed Solution

Add a --json flag (or --output json) to all read-only commands. When set:

  • Suppress emoji, banners, box-drawing, and interactive prompts
  • Print a single JSON object to stdout
  • Exit with code 0 on success, non-zero on error (with JSON error body)

Commands to update

Command JSON output shape
status { deployment: {…}, endpoints: [{name, url, healthy}], connections: [{plugin, id, name, healthy}], projects: [{name, blueprintId}] }
configure connection list [{id, plugin, name, endpoint, organization, enterprise}]
configure scope list (from #55) [{scopeId, name, fullName, plugin, connectionId}]
configure project list (from #56) [{name, description, blueprintId}]

Implementation approach

  1. Add a package-level outputJSON bool flag on rootCmd.PersistentFlags() so it's available to all commands
  2. Create a helper func printJSON(v any) error in cmd/helpers.go that marshals and writes to stdout
  3. Each command's RunE checks outputJSON early and branches to a JSON code path that builds a struct and calls printJSON
  4. Human output remains the default — no behavioral change for interactive users

Example

# Human (default)
$ gh devlake status
╭──────────────────────────────────────────────╮
│  DevLake Status                              │
╰──────────────────────────────────────────────╯
  ✅ Backend API: http://localhost:8080
  ...

# Machine
$ gh devlake status --json
{"deployment":{"method":"local","stateFile":".devlake-local.json"},"endpoints":[{"name":"backend","url":"http://localhost:8080","healthy":true}],"connections":[{"plugin":"github","id":1,"name":"GitHub - my-org","healthy":true}]}

Acceptance Criteria

Target Version

v0.4.x — Foundation for agent-friendly CLI and AI features.

References

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions