Release CLI v0.3.0

Add Midjourney commands and isolate local callback listeners by selected API key.

Author: runapi-builder

README.md

@@ -119,6 +119,42 @@ Build pipelines that need to verify downloads themselves can consume the stable
 curl -fsSL https://runapi.ai/cli/latest.json | jq '.assets["linux-amd64"]'
 ```
 
+## Local callback listener
+
+Local listeners require the credential issued by browser login. On first use, the CLI lists your enabled API keys and lets you choose one by name, stable ID, and masked value. The validated stable ID is written to `.runapi.toml` at the git root, or in the current directory outside a git repository; no credential or signing secret is stored there.
+
+```bash
+runapi login
+runapi listen localhost:3000/webhooks/runapi
+```
+
+Only tasks created with the selected API key are copied to that listener. Tasks created with another key stay isolated, including keys owned by the same Account member. A committed `.runapi.toml` is reusable by the same member on another machine; another member is prompted to select a key they own.
+
+Selection precedence is `--callback-api-key-id` (one invocation only), then project `.runapi.toml`, then the TTY selector. The selector writes the config only after the server validates the session. The config has one allowed field:
+
+```toml
+callback_api_key_id = "token_abc123"
+```
+
+Renaming the API key does not invalidate this stable ID. Do not add credentials, names, masks, signing secrets, forwarding URLs, or `base_url`; unknown fields are rejected.
+
+Agents and non-interactive shells can discover and select the key explicitly:
+
+```bash
+runapi api-keys list --json
+runapi listen localhost:3000/webhooks/runapi --callback-api-key-id token_abc123
+```
+
+Without `--callback-api-key-id` or `.runapi.toml`, a non-interactive invocation returns `callback_api_key_required` with the available key metadata and never chooses automatically. `cli_listen_required` means the active credential did not come from browser login: the imported API key keeps its existing API access, but cannot list or select listener keys. Remove any `--api-key` or `RUNAPI_API_KEY` override, run `runapi login`, then retry `runapi listen`. If the selected key becomes unusable, the listener exits without falling back to another key.
+
+Print the selected key's stable Listen Signing Secret without starting a listener with:
+
+```bash
+RUNAPI_WEBHOOK_SECRET="$(runapi listen --print-secret --callback-api-key-id token_abc123)"
+```
+
+After upgrading from the previous Account-wide listener behavior, update the CLI, run `runapi login` again, and restart listeners. Previous listener sessions and Account-wide listener secrets are invalid after the migration.
+
 ## Agent runtimes
 
 `runapi` ships a portable skill for the major AI agent runtimes. Install it once and the runtime can run RunAPI commands with full inline documentation:

cmd/runapi/README.md

@@ -119,6 +119,42 @@ Build pipelines that need to verify downloads themselves can consume the stable
 curl -fsSL https://runapi.ai/cli/latest.json | jq '.assets["linux-amd64"]'
 ```
 
+## Local callback listener
+
+Local listeners require the credential issued by browser login. On first use, the CLI lists your enabled API keys and lets you choose one by name, stable ID, and masked value. The validated stable ID is written to `.runapi.toml` at the git root, or in the current directory outside a git repository; no credential or signing secret is stored there.
+
+```bash
+runapi login
+runapi listen localhost:3000/webhooks/runapi
+```
+
+Only tasks created with the selected API key are copied to that listener. Tasks created with another key stay isolated, including keys owned by the same Account member. A committed `.runapi.toml` is reusable by the same member on another machine; another member is prompted to select a key they own.
+
+Selection precedence is `--callback-api-key-id` (one invocation only), then project `.runapi.toml`, then the TTY selector. The selector writes the config only after the server validates the session. The config has one allowed field:
+
+```toml
+callback_api_key_id = "token_abc123"
+```
+
+Renaming the API key does not invalidate this stable ID. Do not add credentials, names, masks, signing secrets, forwarding URLs, or `base_url`; unknown fields are rejected.
+
+Agents and non-interactive shells can discover and select the key explicitly:
+
+```bash
+runapi api-keys list --json
+runapi listen localhost:3000/webhooks/runapi --callback-api-key-id token_abc123
+```
+
+Without `--callback-api-key-id` or `.runapi.toml`, a non-interactive invocation returns `callback_api_key_required` with the available key metadata and never chooses automatically. `cli_listen_required` means the active credential did not come from browser login: the imported API key keeps its existing API access, but cannot list or select listener keys. Remove any `--api-key` or `RUNAPI_API_KEY` override, run `runapi login`, then retry `runapi listen`. If the selected key becomes unusable, the listener exits without falling back to another key.
+
+Print the selected key's stable Listen Signing Secret without starting a listener with:
+
+```bash
+RUNAPI_WEBHOOK_SECRET="$(runapi listen --print-secret --callback-api-key-id token_abc123)"
+```
+
+After upgrading from the previous Account-wide listener behavior, update the CLI, run `runapi login` again, and restart listeners. Previous listener sessions and Account-wide listener secrets are invalid after the migration.
+
 ## Agent runtimes
 
 `runapi` ships a portable skill for the major AI agent runtimes. Install it once and the runtime can run RunAPI commands with full inline documentation:

cmd/runapi/api_keys.go

@@ -0,0 +1,144 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+	"text/tabwriter"
+	"time"
+
+	runapi "github.com/runapi-ai/cli/internal/runapi"
+	"github.com/runapi-ai/core-sdk/go/core"
+	"github.com/spf13/cobra"
+)
+
+type callbackAPIKey struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	MaskedToken string `json:"masked_token"`
+	Enabled     bool   `json:"enabled"`
+}
+
+type apiKeysResponse struct {
+	APIKeys []callbackAPIKey `json:"api_keys"`
+}
+
+func (c *cli) apiKeysCommand() *cobra.Command {
+	apiKeys := &cobra.Command{
+		Use:   "api-keys",
+		Short: "Inspect API keys available to CLI listener operations",
+		Args:  cobra.NoArgs,
+	}
+	var outputJSON bool
+	list := &cobra.Command{
+		Use:   "list",
+		Short: "List callback API key candidates",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			apiKey, baseURL, err := c.listenerCredentials()
+			if err != nil {
+				return err
+			}
+			response, err := fetchAPIKeys(cmd.Context(), c.listenHTTPClient(), baseURL, apiKey)
+			if err != nil {
+				return err
+			}
+			if outputJSON {
+				return c.writeJSON(response)
+			}
+
+			writer := tabwriter.NewWriter(c.stdout, 0, 4, 2, ' ', 0)
+			_, _ = fmt.Fprintln(writer, "NAME\tID\tMASKED KEY\tENABLED")
+			for _, key := range response.APIKeys {
+				_, _ = fmt.Fprintf(writer, "%s\t%s\t%s\t%t\n", key.Name, key.ID, key.MaskedToken, key.Enabled)
+			}
+			return writer.Flush()
+		},
+	}
+	list.Flags().BoolVar(&outputJSON, "json", false, "Write the API key list as JSON")
+	apiKeys.AddCommand(list)
+	return apiKeys
+}
+
+func fetchAPIKeys(ctx context.Context, client *http.Client, baseURL, apiKey string) (apiKeysResponse, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, strings.TrimRight(baseURL, "/")+"/api/v1/cli/keys", nil)
+	if err != nil {
+		return apiKeysResponse{}, err
+	}
+	req.Header.Set("X-API-Key", apiKey)
+	req.Header.Set("User-Agent", core.CLIUserAgent(runapi.Version))
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return apiKeysResponse{}, err
+	}
+	defer resp.Body.Close()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return apiKeysResponse{}, err
+	}
+	if resp.StatusCode != http.StatusOK {
+		return apiKeysResponse{}, cliAPIError(resp, body)
+	}
+
+	var response apiKeysResponse
+	if err := json.Unmarshal(body, &response); err != nil {
+		return apiKeysResponse{}, err
+	}
+	return response, nil
+}
+
+func (c *cli) listenerCredentials() (string, string, error) {
+	cfg, err := loadConfig()
+	if err != nil {
+		return "", "", err
+	}
+	apiKey := firstNonEmpty(
+		strings.TrimSpace(c.apiKeyFlag),
+		strings.TrimSpace(os.Getenv("RUNAPI_API_KEY")),
+		strings.TrimSpace(cfg.APIKey),
+	)
+	if apiKey == "" {
+		return "", "", core.NewError(
+			core.ErrAuthentication,
+			"API key required (--api-key, RUNAPI_API_KEY, or runapi login)",
+			http.StatusUnauthorized,
+			"",
+			nil,
+			nil,
+		)
+	}
+	baseURL := strings.TrimRight(firstNonEmpty(
+		strings.TrimSpace(c.baseURLFlag),
+		strings.TrimSpace(os.Getenv("RUNAPI_BASE_URL")),
+		strings.TrimSpace(cfg.BaseURL),
+		core.DefaultBaseURL,
+	), "/")
+	return apiKey, baseURL, nil
+}
+
+func (c *cli) listenHTTPClient() *http.Client {
+	if c.httpClient != nil {
+		return c.httpClient
+	}
+	return &http.Client{Timeout: 30 * time.Second}
+}
+
+func cliAPIError(response *http.Response, body []byte) error {
+	err := core.ErrorFromResponse(response, body)
+	apiErr, ok := err.(*core.Error)
+	if !ok {
+		return err
+	}
+	var payload struct {
+		Code string `json:"code"`
+	}
+	if json.Unmarshal(body, &payload) == nil && payload.Code != "" {
+		apiErr.Code = core.ErrorCode(payload.Code)
+	}
+	return apiErr
+}

cmd/runapi/api_keys_test.go

@@ -0,0 +1,105 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestAPIKeysListJSON(t *testing.T) {
+	isolateConfig(t)
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet || r.URL.Path != "/api/v1/cli/keys" {
+			t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		if got := r.Header.Get("X-API-Key"); got != "cli-credential" {
+			t.Errorf("expected CLI credential header, got %q", got)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"api_keys":[{"id":"token_project","name":"Project key","masked_token":"runapi_abcd••••••••1234","enabled":true}]}`))
+	}))
+	defer server.Close()
+	if err := saveConfig(configFile{APIKey: "cli-credential", BaseURL: server.URL}); err != nil {
+		t.Fatal(err)
+	}
+
+	var stdout bytes.Buffer
+	c := newCLI()
+	c.stdout = &stdout
+	c.stderr = &bytes.Buffer{}
+	c.httpClient = server.Client()
+	cmd := c.command()
+	cmd.SetArgs([]string{"api-keys", "list", "--json"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+
+	var result apiKeysResponse
+	if err := json.Unmarshal(stdout.Bytes(), &result); err != nil {
+		t.Fatal(err)
+	}
+	if len(result.APIKeys) != 1 {
+		t.Fatalf("expected one API key, got %d", len(result.APIKeys))
+	}
+	key := result.APIKeys[0]
+	if key.ID != "token_project" || key.Name != "Project key" || !key.Enabled {
+		t.Fatalf("unexpected API key: %#v", key)
+	}
+}
+
+func TestListenExplainsHowToReplaceAnImportedAPIKey(t *testing.T) {
+	isolateConfig(t)
+	const message = "`runapi listen` requires the CLI credential created by `runapi login` so it can list your eligible API keys and let you select one callback source. Your current API key can keep using its existing API access, but it cannot access listener operations. Remove any `--api-key` or `RUNAPI_API_KEY` override, run `runapi login`, then retry `runapi listen`."
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet || r.URL.Path != "/api/v1/cli/keys" {
+			t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusForbidden)
+		_ = json.NewEncoder(w).Encode(map[string]string{
+			"error": message,
+			"code":  "cli_listen_required",
+		})
+	}))
+	defer server.Close()
+	if err := saveConfig(configFile{APIKey: "imported-api-key", BaseURL: server.URL}); err != nil {
+		t.Fatal(err)
+	}
+
+	var stdout, stderr bytes.Buffer
+	c := newCLI()
+	c.stdout = &stdout
+	c.stderr = &stderr
+	c.httpClient = server.Client()
+	c.projectDir = projectRootFixture(t, "")
+
+	if code := c.run([]string{"listen", "localhost:3000/webhooks/runapi"}); code == 0 {
+		t.Fatal("expected listen to reject an imported API key")
+	}
+
+	var result struct {
+		Error struct {
+			Message string `json:"message"`
+			Code    string `json:"code"`
+		} `json:"error"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &result); err != nil {
+		t.Fatalf("decode JSON error: %v\nstdout=%s", err, stdout.String())
+	}
+	if result.Error.Code != "cli_listen_required" || result.Error.Message != message {
+		t.Fatalf("unexpected JSON error: %#v", result.Error)
+	}
+	for _, expected := range []string{"runapi login", "list your eligible API keys", "RUNAPI_API_KEY"} {
+		if !strings.Contains(stderr.String(), expected) {
+			t.Fatalf("expected stderr to contain %q, got %q", expected, stderr.String())
+		}
+	}
+}