feat: improve agent-friendly CLI behavior (#195)

Author: dylantientcheu

e2e/e2e_test.go

@@ -148,3 +148,8 @@ func TestRules(t *testing.T) {
 func TestSearch(t *testing.T) {
 	runTestsInDir(t, "testscripts/search")
 }
+
+// TestAgentReady tests describe and dry-run contracts.
+func TestAgentReady(t *testing.T) {
+	runTestsInDir(t, "testscripts/agent-ready")
+}

e2e/testscripts/agent-ready/agent-ready.txtar

@@ -0,0 +1,18 @@
+# Runtime schema should be machine-readable
+exec algolia describe search
+! stderr .
+stdout -count=1 '"schemaVersion":"v1"'
+stdout -count=1 '"name":"algolia search"'
+stdout -count=1 '"responseFields"'
+stdout -count=1 '"attributesToRetrieve"'
+
+# Dry-run should validate and preview without mutating
+stdin update.jsonl
+exec algolia objects update test-agent-ready --file - --dry-run --output json
+! stderr .
+stdout -count=1 '"action":"update_objects"'
+stdout -count=1 '"dryRun":true'
+stdout -count=1 '"objectCount":1'
+
+-- update.jsonl --
+{"objectID":"test-agent-ready","name":"preview"}

internal/docs/docs.go

@@ -9,24 +9,27 @@ import (
 )
 
 type Command struct {
-	Name        string
-	Description string
-	Usage       string
-	Aliases     []string
-	Examples    string
-	Slug        string
-	RunInWebCLI bool
+	Name        string   `json:"name"`
+	Description string   `json:"description"`
+	Usage       string   `json:"usage"`
+	Aliases     []string `json:"aliases,omitempty"`
+	Examples    string   `json:"examples,omitempty"`
+	Slug        string   `json:"slug,omitempty"`
+	RunInWebCLI bool     `json:"runInWebCLI,omitempty"`
+	CommandType string   `json:"commandType"`
 
-	Flags map[string][]Flag
+	Annotations map[string]string `json:"annotations,omitempty"`
 
-	SubCommands []Command
+	Flags map[string][]Flag `json:"flags,omitempty"`
+
+	SubCommands []Command `json:"subCommands,omitempty"`
 }
 
 type Flag struct {
-	Name        string
-	Shorthand   string
-	Description string
-	Default     string
+	Name        string `json:"name"`
+	Shorthand   string `json:"shorthand,omitempty"`
+	Description string `json:"description"`
+	Default     string `json:"default"`
 }
 
 func newFlag(flag *pflag.Flag) Flag {
@@ -61,6 +64,8 @@ func newCommand(cmd *cobra.Command) Command {
 		Aliases:     cmd.Aliases,
 		Examples:    cmd.Example,
 		RunInWebCLI: false,
+		CommandType: commandType(cmd),
+		Annotations: cmd.Annotations,
 	}
 	if value, ok := cmd.Annotations["runInWebCLI"]; ok && value != "" {
 		command.RunInWebCLI = true
@@ -89,6 +94,22 @@ func newCommand(cmd *cobra.Command) Command {
 	return command
 }
 
+func commandType(cmd *cobra.Command) string {
+	switch cmd.Name() {
+	case "tail":
+		return "stream"
+	case "search", "browse", "get", "list", "stats", "analyze", "describe", "schema", "open":
+		return "read"
+	case "create", "delete", "clear", "import", "update", "set", "save", "move", "copy", "crawl", "run", "pause", "reindex", "unblock", "remove", "add", "setdefault":
+		return "write"
+	default:
+		if cmd.HasAvailableSubCommands() {
+			return "namespace"
+		}
+		return "other"
+	}
+}
+
 func getCommands(cmd *cobra.Command) []Command {
 	var commands []Command
 	for _, c := range cmd.Commands() {
@@ -113,6 +134,49 @@ func getCommands(cmd *cobra.Command) []Command {
 	return commands
 }
 
+func describeCommand(cmd *cobra.Command) Command {
+	command := newCommand(cmd)
+	if cmd.HasAvailableSubCommands() {
+		command.SubCommands = getCommands(cmd)
+	}
+	return command
+}
+
+// DescribeCommand returns a machine-readable description of a command.
+func DescribeCommand(cmd *cobra.Command) Command {
+	return describeCommand(cmd)
+}
+
+// FindCommand resolves a command path against the provided root command.
+func FindCommand(root *cobra.Command, args []string) (*cobra.Command, error) {
+	current := root
+	for _, arg := range args {
+		next := findChildCommand(current, arg)
+		if next == nil {
+			return nil, cmdutil.FlagErrorf("unknown command %q for %q", arg, current.CommandPath())
+		}
+		current = next
+	}
+	return current, nil
+}
+
+func findChildCommand(cmd *cobra.Command, name string) *cobra.Command {
+	for _, child := range cmd.Commands() {
+		if child.Hidden || child.Name() == "help" {
+			continue
+		}
+		if child.Name() == name {
+			return child
+		}
+		for _, alias := range child.Aliases {
+			if alias == name {
+				return child
+			}
+		}
+	}
+	return nil
+}
+
 type Example struct {
 	Desc          string
 	Code          string

pkg/cmd/apikeys/get/get.go

@@ -56,6 +56,8 @@ func NewGetCmd(f *cmdutil.Factory, runF func(*GetOptions) error) *cobra.Command
 		},
 	}
 
+	opts.PrintFlags.AddFlags(cmd)
+
 	return cmd
 }
 

pkg/cmd/apikeys/get/get_test.go

@@ -57,3 +57,25 @@ func Test_runGetCmd(t *testing.T) {
 		})
 	}
 }
+
+func Test_runGetCmd_outputFlag(t *testing.T) {
+	name := "test"
+	r := httpmock.Registry{}
+	r.Register(
+		httpmock.REST("GET", "1/keys/foo"),
+		httpmock.JSONResponse(search.GetApiKeyResponse{
+			Value:       "foo",
+			Description: &name,
+			Acl:         []search.Acl{search.ACL_SEARCH},
+		}),
+	)
+
+	f, out := test.NewFactory(false, &r, nil, "")
+	cmd := NewGetCmd(f, nil)
+	out, err := test.Execute(cmd, "foo --output ndjson", out)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Contains(t, out.String(), `"value":"foo"`)
+}

pkg/cmd/apikeys/list/list.go

@@ -74,6 +74,14 @@ func runListCmd(opts *ListOptions) error {
 		return err
 	}
 
+	if opts.PrintFlags.HasStructuredOutput() {
+		p, err := opts.PrintFlags.ToPrinter()
+		if err != nil {
+			return err
+		}
+		return p.Print(opts.IO, res)
+	}
+
 	table := printers.NewTablePrinter(opts.IO)
 	if table.IsTTY() {
 		table.AddField("KEY", nil, nil)

pkg/cmd/apikeys/list/list_test.go

@@ -62,3 +62,35 @@ func Test_runListCmd(t *testing.T) {
 		})
 	}
 }
+
+func Test_runListCmd_outputJSON(t *testing.T) {
+	oldNowFn := nowFn
+	nowFn = func() time.Time { return time.Unix(1735689600, 0) } // 2025-01-01T00:00:00Z
+	t.Cleanup(func() { nowFn = oldNowFn })
+
+	name := "test"
+	r := httpmock.Registry{}
+	r.Register(
+		httpmock.REST("GET", "1/keys"),
+		httpmock.JSONResponse(search.ListApiKeysResponse{
+			Keys: []search.GetApiKeyResponse{
+				{
+					Value:       "foo",
+					Description: &name,
+					Acl:         []search.Acl{search.ACL_SEARCH},
+					CreatedAt:   1577836800,
+				},
+			},
+		}),
+	)
+
+	f, out := test.NewFactory(false, &r, nil, "")
+	cmd := NewListCmd(f, nil)
+	out, err := test.Execute(cmd, "--output json", out)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.Contains(t, out.String(), `"keys":[`)
+	assert.Contains(t, out.String(), `"value":"foo"`)
+}

pkg/cmd/crawler/get/get.go

@@ -60,6 +60,8 @@ func NewGetCmd(f *cmdutil.Factory, runF func(*GetOptions) error) *cobra.Command
 	cmd.Flags().
 		BoolVarP(&opts.ConfigOnly, "config-only", "c", false, "Display only the crawler configuration")
 
+	opts.PrintFlags.AddFlags(cmd)
+
 	return cmd
 }
 

pkg/cmd/crawler/get/get_test.go

@@ -0,0 +1,30 @@
+package get
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/algolia/cli/test"
+)
+
+func Test_NewGetCmd_outputFlag(t *testing.T) {
+	f, out := test.NewFactory(false, nil, nil, "")
+
+	called := false
+	cmd := NewGetCmd(f, func(opts *GetOptions) error {
+		called = true
+		assert.Equal(t, "my-crawler", opts.ID)
+		if assert.NotNil(t, opts.PrintFlags.OutputFormat) {
+			assert.Equal(t, "json", *opts.PrintFlags.OutputFormat)
+		}
+		return nil
+	})
+
+	_, err := test.Execute(cmd, "my-crawler --output json", out)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assert.True(t, called)
+}

pkg/cmd/crawler/test/test.go

@@ -81,6 +81,8 @@ func NewTestCmd(f *cmdutil.Factory, runF func(*TestOptions) error) *cobra.Comman
 	cmd.Flags().
 		StringVarP(&configFile, "config", "F", "", "The configuration file to use to override the crawler's configuration. (use \"-\" to read from standard input)")
 
+	opts.PrintFlags.AddFlags(cmd)
+
 	return cmd
 }