feat: improved documentation and flags for client options

stainless-app[bot] · batuhan · commit 5a8537c7de23 · 2026-03-08T21:31:42.000+01:00
diff --git a/README.md b/README.md
@@ -53,25 +53,22 @@ beeper-desktop-cli [resource] <command> [flags...]
 
 ```sh
 beeper-desktop-cli chats search \
-  --account-id local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc \
-  --account-id local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI \
-  --cursor '1725489123456|c29tZUltc2dQYWdl' \
-  --direction before \
-  --inbox primary \
   --include-muted \
-  --last-activity-after 2019-12-27T18:11:19.117Z \
-  --last-activity-before 2019-12-27T18:11:19.117Z \
   --limit 3 \
-  --query x \
-  --scope titles \
-  --type single \
-  --unread-only
+  --type single
 ```
 
 For details about specific commands, use the `--help` flag.
 
-### Global Flags
+### Environment variables
 
+| Environment variable  | Description                                                                                           | Required |
+| --------------------- | ----------------------------------------------------------------------------------------------------- | -------- |
+| `BEEPER_ACCESS_TOKEN` | Bearer access token obtained via OAuth2 PKCE flow or created in-app. Required for all API operations. | yes      |
+
+### Global flags
+
+- `--access-token` - Bearer access token obtained via OAuth2 PKCE flow or created in-app. Required for all API operations. (can also be set with `BEEPER_ACCESS_TOKEN` env var)
 - `--help` - Show command line usage
 - `--debug` - Enable debug logging (includes HTTP request/response details)
 - `--version`, `-v` - Show the CLI version
diff --git a/internal/requestflag/requestflag.go b/internal/requestflag/requestflag.go
@@ -20,16 +20,17 @@ type Flag[
 		[]float64 | []int64 | []bool | any | map[string]any | DateTimeValue | DateValue | TimeValue |
 		string | float64 | int64 | bool,
 ] struct {
-	Name        string        // name of the flag
-	Category    string        // category of the flag, if any
-	DefaultText string        // default text of the flag for usage purposes
-	HideDefault bool          // whether to hide the default value in output
-	Usage       string        // usage string for help output
-	Required    bool          // whether the flag is required or not
-	Hidden      bool          // whether to hide the flag in help output
-	Default     T             // default value for this flag if not set by from any source
-	Aliases     []string      // aliases that are allowed for this flag
-	Validator   func(T) error // custom function to validate this flag value
+	Name        string               // name of the flag
+	Category    string               // category of the flag, if any
+	DefaultText string               // default text of the flag for usage purposes
+	HideDefault bool                 // whether to hide the default value in output
+	Usage       string               // usage string for help output
+	Sources     cli.ValueSourceChain // sources to load flag value from
+	Required    bool                 // whether the flag is required or not
+	Hidden      bool                 // whether to hide the flag in help output
+	Default     T                    // default value for this flag if not set by from any source
+	Aliases     []string             // aliases that are allowed for this flag
+	Validator   func(T) error        // custom function to validate this flag value
 
 	QueryPath  string // location in the request query string to put this flag's value
 	HeaderPath string // location in the request header to put this flag's value
@@ -127,6 +128,22 @@ func (f *Flag[T]) PreParse() error {
 }
 
 func (f *Flag[T]) PostParse() error {
+	if !f.hasBeenSet {
+		if val, source, found := f.Sources.LookupWithSource(); found {
+			if val != "" || reflect.TypeOf(f.value).Kind() == reflect.String {
+				if err := f.Set(f.Name, val); err != nil {
+					return fmt.Errorf(
+						"could not parse %[1]q as %[2]T value from %[3]s for flag %[4]s: %[5]s",
+						val, f.value, source, f.Name, err,
+					)
+				}
+			} else if val == "" && reflect.TypeOf(f.value).Kind() == reflect.Bool {
+				_ = f.Set(f.Name, "false")
+			}
+
+			f.hasBeenSet = true
+		}
+	}
 	return nil
 }
 
@@ -230,8 +247,9 @@ func (f *Flag[T]) GetDefaultText() string {
 	return f.DefaultText
 }
 
+// GetEnvVars returns the env vars for this flag
 func (f *Flag[T]) GetEnvVars() []string {
-	return nil
+	return f.Sources.EnvKeys()
 }
 
 func (f *Flag[T]) IsDefaultVisible() bool {
diff --git a/pkg/cmd/account_test.go b/pkg/cmd/account_test.go
@@ -12,5 +12,6 @@ func TestAccountsList(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"accounts", "list",
+		"--access-token", "string",
 	)
 }
diff --git a/pkg/cmd/accountcontact_test.go b/pkg/cmd/accountcontact_test.go
@@ -12,6 +12,7 @@ func TestAccountsContactsList(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"accounts:contacts", "list",
+		"--access-token", "string",
 		"--account-id", "accountID",
 		"--cursor", "1725489123456|c29tZUltc2dQYWdl",
 		"--direction", "before",
@@ -24,6 +25,7 @@ func TestAccountsContactsSearch(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"accounts:contacts", "search",
+		"--access-token", "string",
 		"--account-id", "accountID",
 		"--query", "x",
 	)
diff --git a/pkg/cmd/asset_test.go b/pkg/cmd/asset_test.go
@@ -12,6 +12,7 @@ func TestAssetsDownload(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"assets", "download",
+		"--access-token", "string",
 		"--url", "mxc://example.org/Q4x9CqGz1pB3Oa6XgJ",
 	)
 }
@@ -20,6 +21,7 @@ func TestAssetsServe(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"assets", "serve",
+		"--access-token", "string",
 		"--url", "x",
 	)
 }
@@ -28,7 +30,8 @@ func TestAssetsUpload(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"assets", "upload",
-		"--file", "",
+		"--access-token", "string",
+		"--file", "...",
 		"--file-name", "fileName",
 		"--mime-type", "mimeType",
 	)
@@ -38,6 +41,7 @@ func TestAssetsUploadBase64(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"assets", "upload-base64",
+		"--access-token", "string",
 		"--content", "x",
 		"--file-name", "fileName",
 		"--mime-type", "mimeType",
diff --git a/pkg/cmd/beeperdesktopapi_test.go b/pkg/cmd/beeperdesktopapi_test.go
@@ -12,6 +12,7 @@ func TestFocus(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"focus",
+		"--access-token", "string",
 		"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",
 		"--draft-attachment-path", "draftAttachmentPath",
 		"--draft-text", "draftText",
@@ -23,6 +24,7 @@ func TestSearch(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"search",
+		"--access-token", "string",
 		"--query", "x",
 	)
 }
diff --git a/pkg/cmd/chat_test.go b/pkg/cmd/chat_test.go
@@ -13,6 +13,7 @@ func TestChatsCreate(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"chats", "create",
+		"--access-token", "string",
 		"--account-id", "accountID",
 		"--allow-invite=true",
 		"--message-text", "messageText",
@@ -49,6 +50,7 @@ func TestChatsRetrieve(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"chats", "retrieve",
+		"--access-token", "string",
 		"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",
 		"--max-participant-count", "50",
 	)
@@ -58,6 +60,7 @@ func TestChatsList(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"chats", "list",
+		"--access-token", "string",
 		"--account-id", "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
 		"--account-id", "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU",
 		"--cursor", "1725489123456|c29tZUltc2dQYWdl",
@@ -69,6 +72,7 @@ func TestChatsArchive(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"chats", "archive",
+		"--access-token", "string",
 		"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",
 		"--archived=true",
 	)
@@ -78,14 +82,15 @@ func TestChatsSearch(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"chats", "search",
+		"--access-token", "string",
 		"--account-id", "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
 		"--account-id", "local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI",
 		"--cursor", "1725489123456|c29tZUltc2dQYWdl",
 		"--direction", "before",
 		"--inbox", "primary",
 		"--include-muted=true",
-		"--last-activity-after", "2019-12-27T18:11:19.117Z",
-		"--last-activity-before", "2019-12-27T18:11:19.117Z",
+		"--last-activity-after", "'2019-12-27T18:11:19.117Z'",
+		"--last-activity-before", "'2019-12-27T18:11:19.117Z'",
 		"--limit", "1",
 		"--query", "x",
 		"--scope", "titles",
diff --git a/pkg/cmd/chatmessagereaction_test.go b/pkg/cmd/chatmessagereaction_test.go
@@ -12,6 +12,7 @@ func TestChatsMessagesReactionsDelete(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"chats:messages:reactions", "delete",
+		"--access-token", "string",
 		"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",
 		"--message-id", "messageID",
 		"--reaction-key", "x",
@@ -22,6 +23,7 @@ func TestChatsMessagesReactionsAdd(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"chats:messages:reactions", "add",
+		"--access-token", "string",
 		"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",
 		"--message-id", "messageID",
 		"--reaction-key", "x",
diff --git a/pkg/cmd/chatreminder_test.go b/pkg/cmd/chatreminder_test.go
@@ -13,6 +13,7 @@ func TestChatsRemindersCreate(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"chats:reminders", "create",
+		"--access-token", "string",
 		"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",
 		"--reminder", "{remindAtMs: 0, dismissOnIncomingMessage: true}",
 	)
@@ -34,6 +35,7 @@ func TestChatsRemindersDelete(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"chats:reminders", "delete",
+		"--access-token", "string",
 		"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",
 	)
 }
diff --git a/pkg/cmd/cmd.go b/pkg/cmd/cmd.go
@@ -12,6 +12,7 @@ import (
 	"strings"
 
 	"github.com/beeper/desktop-api-cli/internal/autocomplete"
+	"github.com/beeper/desktop-api-cli/internal/requestflag"
 	docs "github.com/urfave/cli-docs/v3"
 	"github.com/urfave/cli/v3"
 )
@@ -66,6 +67,11 @@ func init() {
 				Name:  "transform-error",
 				Usage: "The GJSON transformation for errors.",
 			},
+			&requestflag.Flag[string]{
+				Name:    "access-token",
+				Usage:   "Bearer access token obtained via OAuth2 PKCE flow or created in-app. Required for all API operations.",
+				Sources: cli.EnvVars("BEEPER_ACCESS_TOKEN"),
+			},
 		},
 		Commands: []*cli.Command{
 			&focus,
diff --git a/pkg/cmd/cmdutil.go b/pkg/cmd/cmdutil.go
@@ -34,6 +34,7 @@ func getDefaultRequestOptions(cmd *cli.Command) []option.RequestOption {
 		option.WithHeader("X-Stainless-Package-Version", Version),
 		option.WithHeader("X-Stainless-Runtime", "cli"),
 		option.WithHeader("X-Stainless-CLI-Command", cmd.FullName()),
+		option.WithAccessToken(cmd.String("access-token")),
 	}
 
 	// Override base URL if the --base-url flag is provided
diff --git a/pkg/cmd/info_test.go b/pkg/cmd/info_test.go
@@ -12,5 +12,6 @@ func TestInfoRetrieve(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"info", "retrieve",
+		"--access-token", "string",
 	)
 }
diff --git a/pkg/cmd/message_test.go b/pkg/cmd/message_test.go
@@ -13,6 +13,7 @@ func TestMessagesUpdate(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"messages", "update",
+		"--access-token", "string",
 		"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",
 		"--message-id", "messageID",
 		"--text", "x",
@@ -23,6 +24,7 @@ func TestMessagesList(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"messages", "list",
+		"--access-token", "string",
 		"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",
 		"--cursor", "1725489123456|c29tZUltc2dQYWdl",
 		"--direction", "before",
@@ -33,14 +35,15 @@ func TestMessagesSearch(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"messages", "search",
+		"--access-token", "string",
 		"--account-id", "local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc",
 		"--account-id", "local-instagram_ba_eRfQMmnSNy_p7Ih7HL7RduRpKFU",
 		"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",
 		"--chat-id", "1231073",
 		"--chat-type", "group",
 		"--cursor", "1725489123456|c29tZUltc2dQYWdl",
-		"--date-after", "2025-08-01T00:00:00Z",
-		"--date-before", "2025-08-31T23:59:59Z",
+		"--date-after", "'2025-08-01T00:00:00Z'",
+		"--date-before", "'2025-08-31T23:59:59Z'",
 		"--direction", "before",
 		"--exclude-low-priority=true",
 		"--include-muted=true",
@@ -55,6 +58,7 @@ func TestMessagesSend(t *testing.T) {
 	mocktest.TestRunMockTestWithFlags(
 		t,
 		"messages", "send",
+		"--access-token", "string",
 		"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",
 		"--attachment", "{uploadID: uploadID, duration: 0, fileName: fileName, mimeType: mimeType, size: {height: 0, width: 0}, type: gif}",
 		"--reply-to-message-id", "replyToMessageID",

Original file line number	Diff line number	Diff line change
`@@ -12,5 +12,6 @@ func TestAccountsList(t *testing.T) {`
`12`	`12`	`mocktest.TestRunMockTestWithFlags(`
`13`	`13`	`t,`
`14`	`14`	`"accounts", "list",`
	`15`	`+ "--access-token", "string",`
`15`	`16`	`)`
`16`	`17`	`}`
Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,7 @@ func TestChatsRemindersCreate(t *testing.T) {`
`13`	`13`	`mocktest.TestRunMockTestWithFlags(`
`14`	`14`	`t,`
`15`	`15`	`"chats:reminders", "create",`
	`16`	`+ "--access-token", "string",`
`16`	`17`	`"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",`
`17`	`18`	`"--reminder", "{remindAtMs: 0, dismissOnIncomingMessage: true}",`
`18`	`19`	`)`
`@@ -34,6 +35,7 @@ func TestChatsRemindersDelete(t *testing.T) {`
`34`	`35`	`mocktest.TestRunMockTestWithFlags(`
`35`	`36`	`t,`
`36`	`37`	`"chats:reminders", "delete",`
	`38`	`+ "--access-token", "string",`
`37`	`39`	`"--chat-id", "!NCdzlIaMjZUmvmvyHU:beeper.com",`
`38`	`40`	`)`
`39`	`41`	`}`