release: 0.2.0

.github/workflows/publish-release.yml

@@ -10,6 +10,7 @@ on:
   push:
     tags:
       - "v*"
+  workflow_dispatch: {}
 jobs:
   goreleaser:
     runs-on: ubuntu-latest

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0"
+  ".": "0.2.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 30
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/hyperspell%2Fhyperspell-7d29d0843a52840291678a3c6d136f496ae1f956853abaa5003c1284ca2c94aa.yml
-openapi_spec_hash: 010597ad0ec6376fbf2f01ec062787ad
-config_hash: bd8505e17db740d82e578d0edaa9bfe0
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/hyperspell/hyperspell-3ea7819d73f46347d7870c6238e12458921045b6386d6091bffe67906d7a017f.yml
+openapi_spec_hash: 004b15cbe7b318ef25b91f6d45b4cba3
+config_hash: 597eba5e5eaec83a5f0db3d946af8db5

CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.2.0 (2026-05-05)
+
+Full Changelog: [v0.1.0...v0.2.0](https://github.com/hyperspell/hyperspell-cli/compare/v0.1.0...v0.2.0)
+
+### Features
+
+* allow `-` as value representing stdin to binary-only file parameters in CLIs ([40329ac](https://github.com/hyperspell/hyperspell-cli/commit/40329ac0504bec769cdcbd0eda4821b15cf164d1))
+* **api:** api update ([cde57e6](https://github.com/hyperspell/hyperspell-cli/commit/cde57e6cc0907e80bc2fa80d05b6701c3b777863))
+* **api:** api update ([15efdbc](https://github.com/hyperspell/hyperspell-cli/commit/15efdbcd4ea5962464fe5eedc212d0fd601ceb1f))
+* **api:** api update ([6ea47ba](https://github.com/hyperspell/hyperspell-cli/commit/6ea47ba9a0248351256a8ddd0bde7b5575a53eb3))
+* **api:** api update ([05fc238](https://github.com/hyperspell/hyperspell-cli/commit/05fc238a5087e6cd3024fd92eccb7fa23cbb8440))
+* **api:** api update ([2f69100](https://github.com/hyperspell/hyperspell-cli/commit/2f691007ba68d3b18b6a643db158ed16b4848871))
+* **api:** api update ([07389a5](https://github.com/hyperspell/hyperspell-cli/commit/07389a55c46d676894d6392d7c6ed4cf33ac4147))
+* better error message if scheme forgotten in CLI `*_BASE_URL`/`--base-url` ([665e431](https://github.com/hyperspell/hyperspell-cli/commit/665e431d3c39a2ba149168250d080bdf8b7546b5))
+* **cli:** add `--raw-output`/`-r` option to print raw (non-JSON) strings ([4222549](https://github.com/hyperspell/hyperspell-cli/commit/422254937af57c228a18d67191aa8966cceebb45))
+* **cli:** alias parameters in data with `x-stainless-cli-data-alias` ([fc1ebc7](https://github.com/hyperspell/hyperspell-cli/commit/fc1ebc74cf40a58ddb979128852ed202354922cc))
+* **cli:** send filename and content type when reading input from files ([4b76c79](https://github.com/hyperspell/hyperspell-cli/commit/4b76c79a99e8bb0f8a3ef112ccaf3092decb69a3))
+* support passing path and query params over stdin ([14f99ef](https://github.com/hyperspell/hyperspell-cli/commit/14f99ef63dff6a55aca07c84419c42ce25d99142))
+
+
+### Bug Fixes
+
+* **cli:** correctly load zsh autocompletion ([c419250](https://github.com/hyperspell/hyperspell-cli/commit/c419250da2b4345806d79c322c0384742e8b234a))
+* **cli:** fix incompatible Go types for flag generated as array of maps ([a95a486](https://github.com/hyperspell/hyperspell-cli/commit/a95a486ccc528af84af0a8aa0500680982ee6033))
+* fall back to main branch if linking fails in CI ([28b2498](https://github.com/hyperspell/hyperspell-cli/commit/28b24981adf8c8c39a68a44495912a66e63945ea))
+* fix for failing to drop invalid module replace in link script ([ad3cbf1](https://github.com/hyperspell/hyperspell-cli/commit/ad3cbf15ab7a70f3318ae32d95b7f6bebeaebceb))
+* fix quoting typo ([d4f3537](https://github.com/hyperspell/hyperspell-cli/commit/d4f35370e45ed2cc4deceeb6b8fae13f0a07fb63))
+* flags for nullable body scalar fields are strictly typed ([c983439](https://github.com/hyperspell/hyperspell-cli/commit/c9834390753ff2facace1035b6b692e73a73e81a))
+
+
+### Chores
+
+* add documentation for ./scripts/link ([2586047](https://github.com/hyperspell/hyperspell-cli/commit/2586047b1af969fcd3b5c21e52c072a7b620118d))
+* **ci:** support manually triggering release workflow ([b5836aa](https://github.com/hyperspell/hyperspell-cli/commit/b5836aa567c2ba79cf6ad7a8706de0ef196ed317))
+* **cli:** additional test cases for `ShowJSONIterator` ([5784e71](https://github.com/hyperspell/hyperspell-cli/commit/5784e710f1021b0939a8985eedaa0c80b0b9df0b))
+* **cli:** fall back to JSON when using default "explore" with non-TTY ([1b5c7e9](https://github.com/hyperspell/hyperspell-cli/commit/1b5c7e9de0a6ceaf663c5a06365a0ce1ec11cca4))
+* **cli:** let `--format raw` be used in conjunction with `--transform` ([d9c0c77](https://github.com/hyperspell/hyperspell-cli/commit/d9c0c77f238264b97af2c5fa8aacbd71de7f6f4b))
+* **cli:** switch long lists of positional args over to param structs ([4a9e250](https://github.com/hyperspell/hyperspell-cli/commit/4a9e2508c2605e814c40980baf343dbda59f28b8))
+* **cli:** use `ShowJSONOpts` as argument to `formatJSON` instead of many positionals ([9e0c109](https://github.com/hyperspell/hyperspell-cli/commit/9e0c10938023ffbd46ca50c61baf2c3353df23d5))
+* **internal:** more robust bootstrap script ([014bf27](https://github.com/hyperspell/hyperspell-cli/commit/014bf271f51526dab8ae459bd514bab798c8062d))
+* mark all CLI-related tests in Go with `t.Parallel()` ([5fc2402](https://github.com/hyperspell/hyperspell-cli/commit/5fc240280f247a2a3817b37e359c7c674048a448))
+* modify CLI tests to inject stdout so mutating `os.Stdout` isn't necessary ([b7fd553](https://github.com/hyperspell/hyperspell-cli/commit/b7fd5533571992857a741f834af4d272b8ad2b6d))
+* switch some CLI Go tests from `os.Chdir` to `t.Chdir` ([2f49e45](https://github.com/hyperspell/hyperspell-cli/commit/2f49e45e69e821c97605e3929f4d6864f2b306e7))
+* **tests:** bump steady to v0.22.1 ([522092e](https://github.com/hyperspell/hyperspell-cli/commit/522092e2767802d6e258353c4bb374f16f2751d5))
+
+
+### Documentation
+
+* update examples ([62e382b](https://github.com/hyperspell/hyperspell-cli/commit/62e382b449383807ab1568d97c5f461fed2c702c))
+
 ## 0.1.0 (2026-04-02)
 
 Full Changelog: [v0.0.1...v0.1.0](https://github.com/hyperspell/hyperspell-cli/compare/v0.0.1...v0.1.0)

README.md

@@ -56,7 +56,7 @@ hyperspell [resource] <command> [flags...]
 ```sh
 hyperspell memories add \
   --api-key 'My API Key' \
-  --text text
+  --text ...
 ```
 
 For details about specific commands, use the `--help` flag.
@@ -119,3 +119,23 @@ base64-encoding). Note that absolute paths will begin with `@file://` or
 ```bash
 hyperspell <command> --arg @data://file.txt
 ```
+
+## Linking different Go SDK versions
+
+You can link the CLI against a different version of the Hyperspell Go SDK
+for development purposes using the `./scripts/link` script.
+
+To link to a specific version from a repository (version can be a branch,
+git tag, or commit hash):
+
+```bash
+./scripts/link github.com/org/repo@version
+```
+
+To link to a local copy of the SDK:
+
+```bash
+./scripts/link ../path/to/hyperspell-go
+```
+
+If you run the link script without any arguments, it will default to `../hyperspell-go`.

cmd/hyperspell/main.go

@@ -23,6 +23,13 @@ func main() {
 		prepareForAutocomplete(app)
 	}
 
+	if baseURL, ok := os.LookupEnv("HYPERSPELL_BASE_URL"); ok {
+		if err := cmd.ValidateBaseURL(baseURL, "HYPERSPELL_BASE_URL"); err != nil {
+			fmt.Fprintf(os.Stderr, "%s\n", err.Error())
+			os.Exit(1)
+		}
+	}
+
 	if err := app.Run(context.Background(), os.Args); err != nil {
 		exitCode := 1
 
@@ -36,7 +43,12 @@ func main() {
 			fmt.Fprintf(os.Stderr, "%s %q: %d %s\n", apierr.Request.Method, apierr.Request.URL, apierr.Response.StatusCode, http.StatusText(apierr.Response.StatusCode))
 			format := app.String("format-error")
 			json := gjson.Parse(apierr.RawJSON())
-			show_err := cmd.ShowJSON(os.Stdout, "Error", json, format, app.String("transform-error"))
+			show_err := cmd.ShowJSON(json, cmd.ShowJSONOpts{
+				ExplicitFormat: app.IsSet("format-error"),
+				Format:         format,
+				Title:          "Error",
+				Transform:      app.String("transform-error"),
+			})
 			if show_err != nil {
 				// Just print the original error:
 				fmt.Fprintf(os.Stderr, "%s\n", err.Error())

internal/apiform/form_test.go

@@ -85,8 +85,12 @@ var tests = map[string]struct {
 }
 
 func TestEncode(t *testing.T) {
+	t.Parallel()
+
 	for name, test := range tests {
 		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
 			buf := bytes.NewBuffer(nil)
 			writer := multipart.NewWriter(buf)
 			writer.SetBoundary("xxx")

internal/apiquery/query_test.go

@@ -6,6 +6,8 @@ import (
 )
 
 func TestEncode(t *testing.T) {
+	t.Parallel()
+
 	tests := map[string]struct {
 		val      any
 		settings QuerySettings
@@ -114,6 +116,8 @@ func TestEncode(t *testing.T) {
 
 	for name, test := range tests {
 		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
 			query := map[string]any{"query": test.val}
 			values, err := MarshalWithSettings(query, test.settings)
 			if err != nil {

internal/autocomplete/autocomplete_test.go

@@ -8,6 +8,8 @@ import (
 )
 
 func TestGetCompletions_EmptyArgs(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{Name: "generate", Usage: "Generate SDK"},
@@ -26,6 +28,8 @@ func TestGetCompletions_EmptyArgs(t *testing.T) {
 }
 
 func TestGetCompletions_SubcommandPrefix(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{Name: "generate", Usage: "Generate SDK"},
@@ -43,6 +47,8 @@ func TestGetCompletions_SubcommandPrefix(t *testing.T) {
 }
 
 func TestGetCompletions_HiddenCommand(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{Name: "visible", Usage: "Visible command"},
@@ -57,6 +63,8 @@ func TestGetCompletions_HiddenCommand(t *testing.T) {
 }
 
 func TestGetCompletions_NestedSubcommand(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{
@@ -79,6 +87,8 @@ func TestGetCompletions_NestedSubcommand(t *testing.T) {
 }
 
 func TestGetCompletions_FlagCompletion(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{
@@ -102,6 +112,8 @@ func TestGetCompletions_FlagCompletion(t *testing.T) {
 }
 
 func TestGetCompletions_ShortFlagCompletion(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{
@@ -123,6 +135,8 @@ func TestGetCompletions_ShortFlagCompletion(t *testing.T) {
 }
 
 func TestGetCompletions_FileFlagBehavior(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{
@@ -142,6 +156,8 @@ func TestGetCompletions_FileFlagBehavior(t *testing.T) {
 }
 
 func TestGetCompletions_NonBoolFlagValue(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{
@@ -161,6 +177,8 @@ func TestGetCompletions_NonBoolFlagValue(t *testing.T) {
 }
 
 func TestGetCompletions_BoolFlagDoesNotBlockCompletion(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{
@@ -185,6 +203,8 @@ func TestGetCompletions_BoolFlagDoesNotBlockCompletion(t *testing.T) {
 }
 
 func TestGetCompletions_ColonCommands_NoColonTyped(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{Name: "config:get", Usage: "Get config value"},
@@ -202,6 +222,8 @@ func TestGetCompletions_ColonCommands_NoColonTyped(t *testing.T) {
 }
 
 func TestGetCompletions_ColonCommands_ColonTyped_Bash(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{Name: "config:get", Usage: "Get config value"},
@@ -221,6 +243,8 @@ func TestGetCompletions_ColonCommands_ColonTyped_Bash(t *testing.T) {
 }
 
 func TestGetCompletions_ColonCommands_ColonTyped_Zsh(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{Name: "config:get", Usage: "Get config value"},
@@ -240,6 +264,8 @@ func TestGetCompletions_ColonCommands_ColonTyped_Zsh(t *testing.T) {
 }
 
 func TestGetCompletions_BashStyleColonCompletion(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{Name: "config:get", Usage: "Get config value"},
@@ -257,6 +283,8 @@ func TestGetCompletions_BashStyleColonCompletion(t *testing.T) {
 }
 
 func TestGetCompletions_BashStyleColonCompletion_NoMatch(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{Name: "config:get", Usage: "Get config value"},
@@ -271,6 +299,8 @@ func TestGetCompletions_BashStyleColonCompletion_NoMatch(t *testing.T) {
 }
 
 func TestGetCompletions_ZshStyleColonCompletion(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{Name: "config:get", Usage: "Get config value"},
@@ -287,6 +317,8 @@ func TestGetCompletions_ZshStyleColonCompletion(t *testing.T) {
 }
 
 func TestGetCompletions_MixedColonAndRegularCommands(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{Name: "generate", Usage: "Generate SDK"},
@@ -305,6 +337,8 @@ func TestGetCompletions_MixedColonAndRegularCommands(t *testing.T) {
 }
 
 func TestGetCompletions_FlagWithBoolFlagSkipsValue(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{
@@ -329,6 +363,8 @@ func TestGetCompletions_FlagWithBoolFlagSkipsValue(t *testing.T) {
 }
 
 func TestGetCompletions_MultipleFlagsBeforeSubcommand(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{
@@ -353,6 +389,8 @@ func TestGetCompletions_MultipleFlagsBeforeSubcommand(t *testing.T) {
 }
 
 func TestGetCompletions_CommandAliases(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{Name: "generate", Aliases: []string{"gen", "g"}, Usage: "Generate SDK"},
@@ -372,6 +410,8 @@ func TestGetCompletions_CommandAliases(t *testing.T) {
 }
 
 func TestGetCompletions_AllFlagsWhenNoPrefix(t *testing.T) {
+	t.Parallel()
+
 	root := &cli.Command{
 		Commands: []*cli.Command{
 			{

internal/autocomplete/shellscripts/zsh_autocomplete.zsh

@@ -1,5 +1,4 @@
-#!/bin/zsh
-compdef ____APPNAME___zsh_autocomplete __APPNAME__
+#compdef __APPNAME__
 
 ____APPNAME___zsh_autocomplete() {
 
@@ -44,3 +43,14 @@ ____APPNAME___zsh_autocomplete() {
       ;;
   esac
 }
+
+# When installed in fpath (e.g., via Homebrew's zsh_completion stanza), this file
+# is autoloaded as the function ___APPNAME__ and its body becomes that function's
+# body. Detect that case via funcstack and dispatch to the completion function.
+# When sourced (e.g., `source <(__APPNAME__ @completion zsh)`), register the
+# function with compdef instead.
+if [[ "${funcstack[1]}" = "___APPNAME__" ]]; then
+  ____APPNAME___zsh_autocomplete "$@"
+else
+  compdef ____APPNAME___zsh_autocomplete __APPNAME__
+fi

internal/jsonview/explorer_test.go

@@ -10,6 +10,8 @@ import (
 )
 
 func TestNavigateForward_EmptyRowData(t *testing.T) {
+	t.Parallel()
+
 	// An empty JSON array produces a TableView with no rows.
 	emptyArray := gjson.Parse("[]")
 	view, err := newTableView("", emptyArray, false)
@@ -38,6 +40,8 @@ type rawJSONItem struct {
 func (r rawJSONItem) RawJSON() string { return r.raw }
 
 func TestMarshalItemsToJSONArray_WithHasRawJSON(t *testing.T) {
+	t.Parallel()
+
 	items := []any{
 		rawJSONItem{raw: `{"id":1,"name":"alice"}`},
 		rawJSONItem{raw: `{"id":2,"name":"bob"}`},
@@ -49,6 +53,8 @@ func TestMarshalItemsToJSONArray_WithHasRawJSON(t *testing.T) {
 }
 
 func TestMarshalItemsToJSONArray_WithoutHasRawJSON(t *testing.T) {
+	t.Parallel()
+
 	items := []any{
 		map[string]any{"id": 1, "name": "alice"},
 		map[string]any{"id": 2, "name": "bob"},