Improve CLI usability and improve automation cases (e.g. agents/LLMs) #507

toolmantim · 2025-07-16T13:46:51Z

Update BK CLI to improve agent use cases, as well as help and examples for human users too.

Migrated from Cobra to Kong framework
Improved help text for better readability by humans and LLMs
Dynamic shell completions with comprehensive flag and subcommand suggestions
Better error messages
Various improvements to make things more LLM friendly:
- Non-interactive modes for bk build watch
- Add bk job logs <job-id> command for viewing individual job logs
- Add --logs and --failed-only flags to bk build download command
New --output flag for all data query commands (deprecated --json)

See UPGRADING.md for upgrade instructions.

Replaces #478

mcncl · 2025-07-16T23:23:52Z

@toolmantim that diff 😂 I'll look at this one file at a time, but I'm very excited if this does what it says on the tin

toolmantim · 2025-07-17T00:00:18Z

internal/http/client.go

 	}
 	req.Header.Set("Accept", "application/json")

+	// Set custom headers (these can override common headers)


custom headers support regressed in #447, this includes a fix for that

toolmantim · 2025-07-17T00:02:38Z

@mcncl thanks! Lol yeah, no avoiding the big diff sadly. I just pushed a few final things, including a fix to custom headers. Feel free to update this branch yourself now.

scadu

Still reading through the PR, but left some initial feedback.

pkg/cli/other.go

pkg/cli/build.go

pkg/cli/error_formatter.go

pkg/cli/headerflag.go

pkg/cli/other.go

AGENT.md

pkg/cli/user.go

toolmantim · 2025-07-20T06:49:10Z

Related musings that I saw posted today: https://www.notcheckmark.com/2025/07/rethinking-cli-interfaces-for-ai/

I'll give this a really good manual test this week. If you can assist with code reviews, and someone can also give it a quick manual test, we should be good.

luispadron · 2025-07-22T21:35:28Z

Was just about to open up an issue to allow --json output when possible (for use in scripts, etc). Would love to see this supported for commands like bk build view and bk artifacts list

- Migrated from Cobra to Kong framework - Improved help text for better readability by humans and LLMs - Dynamic shell completions with comprehensive flag and subcommand suggestions - Better error messages - Various improvements to make things more LLM friendly: - Non-interactive modes for `bk build watch` - Add `bk job logs <job-id>`` command for viewing individual job logs - Add `--logs` and `--failed-only` flags to `bk build download` command - New `--output` flag for all data query commands (deprecated `--json`) See UPGRADING.md for breaking changes and upgrade instructions.

Amp-Thread: https://ampcode.com/threads/T-7317d394-b949-4d03-9495-73aa1df9b383 Co-authored-by: Amp <[email protected]>

- Add Bubble Tea TUI support for agent list command (default behavior) - Add TUI progress bars for agent stop when stopping multiple agents - Add live refresh mode for build watch command (default behavior) - Match Cobra's default TUI behavior exactly - Add basic tests for help text validation The TUI features now have full parity with the Cobra implementation, using the same default behavior without requiring additional flags. Amp-Thread: https://ampcode.com/threads/T-ba73c50b-9366-47dd-8be7-1fbfeb5106a1 Co-authored-by: Amp <[email protected]>

- Agent list: Only show TUI when stdout is a TTY, otherwise show table - Agent stop: Only show progress bars for multiple agents when TTY available - Build watch: Only use clear screen refresh when TTY available - Add fallback behavior for non-TTY environments (CI/CD compatibility) - Add tests documenting TTY detection behavior This ensures commands work properly in non-interactive environments while preserving the rich TUI experience for terminal users. Amp-Thread: https://ampcode.com/threads/T-ba73c50b-9366-47dd-8be7-1fbfeb5106a1 Co-authored-by: Amp <[email protected]>

Amp-Thread: https://ampcode.com/threads/T-7041b50d-7f48-472f-a94c-3dd88ae3096b Co-authored-by: Amp <[email protected]>

- Convert whoami from Cobra to Kong CLI framework - Add structured output support (JSON, YAML, table) - Include help text and examples - Preserve original functionality from main branch Co-authored-by: Amp <[email protected]> Amp-Thread-ID: https://ampcode.com/threads/T-9b44beb4-1b27-47f7-b450-8b0b97694529 Co-authored-by: Amp <[email protected]> Amp-Thread-ID: https://ampcode.com/threads/T-9b44beb4-1b27-47f7-b450-8b0b97694529

scadu

Left a few more comments, mostly around possible race conditions and validation.

scadu · 2025-07-29T10:08:46Z

main

Binary should be removed from the repo.

scadu · 2025-07-29T10:17:54Z

internal/config/config.go

 	key := fmt.Sprintf("organizations.%s.api_token", slug)
+
+	// Check for deprecated BK_ACCESS_TOKEN and warn if used
+	legacyToken := os.Getenv("BK_ACCESS_TOKEN")


Could it lead to a race condition when sync.One is a global, but warning logic depends on env variables that can change between calls?

scadu · 2025-07-29T10:19:18Z

internal/agent/list.go

+	return m.loadAgents(true)
+}
+
+func (m *AgentListModel) loadAgents(isRefresh bool) tea.Cmd {


Looks like it could append indefinitely in long-running sessions? Is there a limit or pagination somewhere?

scadu · 2025-07-29T10:27:24Z

pkg/cli/agent.go

+				_, err = f.RestAPIClient.Agents.Stop(ctx, org, agentID, a.Force)
+			})
+			if spinErr != nil {
+				errChan <- spinErr


Could it be another race condition when multiple goroutines write to errChan and reading from shared state? Might be worth looking into https://pkg.go.dev/golang.org/x/sync/errgroup which provides a friendly abstraction over goroutines handling.

scadu · 2025-07-29T10:35:10Z

internal/validation/scopes/scopes.go

Do we have equivalent of that in Kong version?

mcncl · 2025-07-30T00:07:08Z

Taking a little tour through this and I can see that there are at least some helpers missing, like bk build new without a default branch just returns a 402, rather than a helpful error re: missing default branch and to use --branch.

I think it's heading down the right path; basic functionality seems to persist, but I think we'd need to fine tooth-comb it.

toolmantim · 2025-08-09T11:58:23Z

thanks @scadu & @mcncl — will update this shortly

toolmantim requested a review from a team as a code owner July 16, 2025 13:46

toolmantim force-pushed the kong branch from 1e110f7 to a1d3d1e Compare July 16, 2025 23:04

toolmantim changed the title ~~Switch CLI from Cobra to Kong framework~~ Improve CLI usability and improve automation cases (e.g. LLMs) Jul 16, 2025

toolmantim changed the title ~~Improve CLI usability and improve automation cases (e.g. LLMs)~~ Improve CLI usability and improve automation cases (e.g. agents/LLMs) Jul 16, 2025

toolmantim force-pushed the kong branch 5 times, most recently from 943ee03 to 27555fb Compare July 16, 2025 23:59

toolmantim commented Jul 17, 2025

View reviewed changes

scadu reviewed Jul 17, 2025

View reviewed changes

toolmantim force-pushed the kong branch 2 times, most recently from 2dd1052 to 72c2a3e Compare July 18, 2025 11:08

toolmantim and others added 11 commits July 24, 2025 22:35

Restore support for build numbers without pipeline context

69abd63

Amp-Thread: https://ampcode.com/threads/T-7317d394-b949-4d03-9495-73aa1df9b383 Co-authored-by: Amp <[email protected]>

Add validation for --failed-only flag requiring --logs

3c7db83

Amp-Thread: https://ampcode.com/threads/T-7317d394-b949-4d03-9495-73aa1df9b383 Co-authored-by: Amp <[email protected]>

Remove contains wrapper function and use strings.Contains directly

56b81af

Remove unnecessary goroutine in user invite error handling

0b61271

Amp-Thread: https://ampcode.com/threads/T-7317d394-b949-4d03-9495-73aa1df9b383 Co-authored-by: Amp <[email protected]>

Add basic tests for HeaderFlag and parseBuildIdentifier

292ddc9

Amp-Thread: https://ampcode.com/threads/T-7317d394-b949-4d03-9495-73aa1df9b383 Co-authored-by: Amp <[email protected]>

Move factory package out of cmd to prepare for Cobra removal

394f80f

refactor: complete Cobra to Kong migration cleanup

dc6bdb1

Clean up AGENT.md formatting and redundant text

d6eb143

Amp-Thread: https://ampcode.com/threads/T-7041b50d-7f48-472f-a94c-3dd88ae3096b Co-authored-by: Amp <[email protected]>

toolmantim force-pushed the kong branch from ce810e5 to 0c049ab Compare July 24, 2025 12:59

toolmantim force-pushed the kong branch from 0c049ab to f4d1198 Compare July 24, 2025 13:01

toolmantim added 5 commits July 25, 2025 22:59

Fix refresh issue on use command with latest huh

c6b935a

Fix agent list

a9641e0

Fix job retry and unblock

7408a55

Reorganize

8d9a727

fmt/lint

04cf36b

scadu reviewed Jul 29, 2025

View reviewed changes

Uh oh!

Improve CLI usability and improve automation cases (e.g. agents/LLMs) #507

Are you sure you want to change the base?

Improve CLI usability and improve automation cases (e.g. agents/LLMs) #507

Uh oh!

Conversation

toolmantim commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcncl commented Jul 16, 2025

Uh oh!

toolmantim Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

toolmantim commented Jul 17, 2025

Uh oh!

scadu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

toolmantim commented Jul 20, 2025

Uh oh!

luispadron commented Jul 22, 2025

Uh oh!

scadu left a comment

Choose a reason for hiding this comment

Uh oh!

scadu Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

scadu Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

scadu Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

scadu Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

scadu Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

mcncl commented Jul 30, 2025

Uh oh!

toolmantim commented Aug 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

toolmantim commented Jul 16, 2025 •

edited

Loading