feat(cli): improve auth validation, paginated responses, and UX (#425)

- Add ValidateAndRefresh to verify tokens with Supabase instead of only checking local expiry
- Add `dash ping` command to verify API connectivity for current project
- Fix paginated response handling with generic PaginatedResponse[T] type
- Fix CreateProjectResponse/RotateKeyResponse to match actual API output
- Clear credentials.json on logout alongside auth.json
- Remove ACONTEXT_API_KEY/ACONTEXT_API_TOKEN env var fallbacks (use credentials.json)
- Rename artifacts `ls` subcommand to `list` for consistency
- Fix TUI input to handle paste (multi-rune) correctly
- Add comprehensive test coverage for API client methods
- Update SKILL.md docs with ping command and improved instructions

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: GenerQAQ

landingpage/public/SKILL.md

@@ -23,10 +23,15 @@ Acontext provides Agent Skills as a Memory Layer for production AI agents. It pr
 
 ### 1. Install Acontext CLI
 
+If Acontext CLI is already installed, check for updates first:
+```bash
+acontext upgrade
+```
+
+If not installed, install it:
 ```bash
 curl -fsSL https://install.acontext.io | sh
 ```
-After installation, restart your shell or run `source ~/.bashrc` (or `~/.zshrc`) to make sure the CLI is in your PATH.
 
 > For system-wide installation:
 > ```bash
@@ -41,6 +46,7 @@ acontext login
 - If you're in a Interactive Terminal(TTY), this command will open a browser for OAuth, then guides you through project creation. Your API key is saved automatically.
 - If you're in a Non-interactive Terminal(agent/CI), this command will print a login URL for the user to open manually. After user completes, run `acontext login --poll` to finish authentication.
 - Set up a project via `acontext dash projects` commands. If Acontext has existing projects, make sure the user wants to use an existing project or create a new project for you.
+
 ### 3. Add Acontext to Your Agent
 
 Both plugins automatically read your API key and user email from `~/.acontext/credentials.json` and `~/.acontext/auth.json` (written by `acontext login`). No manual configuration is needed after login.
@@ -88,18 +94,22 @@ openclaw gateway
 After you have logged in, you can manage Acontext projects via CLI:
 
 1. `acontext dash projects list --json` — list available projects
-2. If user ask you to use a existing Acontext project, you should let the user to provider the api key. And then switch to this project `acontext dash projects select --project <project-id> --api-key <sk-ac-...>`. 
-3. To create, ask for an org name and project name, then run: `acontext dash projects create --name <project-name> --org <org-id>`, this command would return the API Key to you, and then select to the new project.
+2. If user ask you to use a existing Acontext project, you should let the user to provide the api key. And then switch to this project `acontext dash projects select --project <project-id> --api-key <sk-ac-...>`.
+3. To create, ask for an org name and project name, then run: `acontext dash projects create --name <project-name> --org <org-id>`. This command returns the API key and auto-saves it as the default project (no need to run `select` afterwards).
+4. After select or create, verify the project is configured correctly:
+   - Check that `~/.acontext/credentials.json` contains the project key.
+   - Run `acontext dash ping` to verify API connectivity. A successful response confirms the project is reachable.
 
 ## CLI Commands Reference
 
 
 All dashboard commands are under `acontext dash`:
 
-| Command Group   | Subcommands                         | Description                            |
-| --------------- | ----------------------------------- | -------------------------------------- |
-| `dash projects` | `list`, `select`, `create`, `stats` | Manage projects and organizations      |
-| `dash open`     | —                                   | Open the Acontext Dashboard in browser |
+| Command Group   | Subcommands                                   | Description                            |
+| --------------- | --------------------------------------------- | -------------------------------------- |
+| `dash projects` | `list`, `select`, `create`, `delete`, `stats` | Manage projects and organizations      |
+| `dash ping`     | —                                             | Verify API connectivity for the current project |
+| `dash open`     | —                                             | Open the Acontext Dashboard in browser |
 
 ### Skill Commands
 
@@ -118,7 +128,7 @@ The directory must contain a `SKILL.md` with name and description in YAML front-
 | Command            | Description                       |
 | ------------------ | --------------------------------- |
 | `acontext login`   | Log in via browser OAuth          |
-| `acontext logout`  | Clear stored credentials          |
+| `acontext logout`  | Clear stored credentials (auth.json + credentials.json) |
 | `acontext whoami`  | Show the currently logged-in user |
 | `acontext version` | Show version info                 |
 | `acontext upgrade` | Upgrade CLI to latest version     |
@@ -194,9 +204,10 @@ Restart your shell or run `source ~/.bashrc` / `source ~/.zshrc`. The installer
 
 ### API returns 401 Unauthorized
 
-- Verify your API key with `acontext whoami`
-- Re-login with `acontext login`
-- For CI/CD, ensure `ACONTEXT_API_KEY` is set correctly
+- Run `acontext dash ping` to check if the current project key is valid
+- If ping fails, re-select with a valid API key: `acontext dash projects select --project <id> --api-key <sk-ac-...>`
+- Verify login status with `acontext whoami`
+- Re-login with `acontext login` if needed
 
 ### Claude Code plugin not working
 

src/client/acontext-cli/cmd/dash.go

@@ -2,7 +2,6 @@ package cmd
 
 import (
 	"fmt"
-	"os"
 
 	"github.com/memodb-io/Acontext/acontext-cli/internal/api"
 	"github.com/memodb-io/Acontext/acontext-cli/internal/auth"
@@ -45,11 +44,9 @@ var DashCmd = &cobra.Command{
 		if err != nil || af == nil {
 			return fmt.Errorf("not logged in — run 'acontext login' first")
 		}
-		if af.IsExpired() {
-			af, err = auth.RefreshIfNeeded(af)
-			if err != nil {
-				return fmt.Errorf("session expired — run 'acontext login' again")
-			}
+		af, err = auth.ValidateAndRefresh(af)
+		if err != nil {
+			return fmt.Errorf("session invalid — run 'acontext login' again: %w", err)
 		}
 		dashUserEmail = af.User.Email
 		dashUserID = af.User.ID
@@ -58,16 +55,13 @@ var DashCmd = &cobra.Command{
 		// 2. Admin client always available (JWT only)
 		dashAdminClient = api.NewAdminClient(dashBaseURL, af.AccessToken)
 
-		// 3. Resolve API key for /api/v1 routes
+		// 3. Resolve API key for /api/v1 routes: --api-key flag > --project flag > credentials.json default
 		apiKey := dashAPIKey
-		if apiKey == "" {
-			apiKey = os.Getenv("ACONTEXT_API_KEY")
-		}
 		if apiKey == "" && dashProject != "" {
 			apiKey = auth.GetProjectKey(dashProject)
 		}
 		if apiKey == "" {
-			// Try default project
+			// Try default project from credentials.json
 			ks, _ := auth.LoadKeyStore()
 			if ks != nil && ks.DefaultProject != "" {
 				apiKey = ks.Keys[ks.DefaultProject]
@@ -86,7 +80,7 @@ var DashCmd = &cobra.Command{
 }
 
 func init() {
-	DashCmd.PersistentFlags().StringVar(&dashAPIKey, "api-key", "", "Project API key (or set ACONTEXT_API_KEY)")
+	DashCmd.PersistentFlags().StringVar(&dashAPIKey, "api-key", "", "Project API key (overrides credentials.json)")
 	DashCmd.PersistentFlags().StringVar(&dashProject, "project", "", "Project ID to use")
 	DashCmd.PersistentFlags().BoolVar(&dashJSON, "json", false, "Output as JSON")
 	DashCmd.PersistentFlags().StringVar(&dashBaseURL, "base-url", "", "API base URL override")

src/client/acontext-cli/cmd/dash_artifacts.go

@@ -13,8 +13,8 @@ import (
 func init() {
 	artifactsCmd := &cobra.Command{Use: "artifacts", Short: "Manage artifacts within a disk"}
 
-	lsCmd := &cobra.Command{
-		Use: "ls <disk-id>", Short: "List artifacts in a disk", Args: cobra.ExactArgs(1),
+	listCmd := &cobra.Command{
+		Use: "list <disk-id>", Short: "List artifacts in a disk", Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			c, err := requireClient()
 			if err != nil {
@@ -85,6 +85,6 @@ func init() {
 	}
 	deleteCmd.Flags().BoolP("yes", "y", false, "Skip confirmation prompt")
 
-	artifactsCmd.AddCommand(lsCmd, uploadCmd, deleteCmd)
+	artifactsCmd.AddCommand(listCmd, uploadCmd, deleteCmd)
 	DashCmd.AddCommand(artifactsCmd)
 }

src/client/acontext-cli/cmd/dash_ping.go

@@ -0,0 +1,53 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/memodb-io/Acontext/acontext-cli/internal/output"
+	"github.com/memodb-io/Acontext/acontext-cli/internal/tui"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	pingCmd := &cobra.Command{
+		Use:   "ping",
+		Short: "Check connectivity to the Acontext API",
+		Long:  "Verifies that the current project's API key is valid and the API is reachable.",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			client, err := requireClient()
+			if err != nil {
+				return err
+			}
+
+			if err := client.Ping(cmd.Context()); err != nil {
+				if dashJSON {
+					return output.RenderJSON(map[string]interface{}{
+						"status":  "error",
+						"project": dashProject,
+						"error":   err.Error(),
+					})
+				}
+				fmt.Printf("Ping failed for project %s: %v\n", dashProject, err)
+				fmt.Println()
+				fmt.Println("To fix this, re-select your project with a valid API key:")
+				fmt.Printf("  acontext dash projects select --project %s --api-key <sk-ac-...>\n", dashProject)
+				fmt.Println()
+				fmt.Println("The API key can be found on the Acontext Dashboard:")
+				fmt.Println("  https://dash.acontext.io")
+				return fmt.Errorf("ping failed")
+			}
+
+			if dashJSON {
+				return output.RenderJSON(map[string]interface{}{
+					"status":  "ok",
+					"project": dashProject,
+				})
+			}
+
+			fmt.Println(tui.RenderSuccess(fmt.Sprintf("Project %s is reachable. Setup complete.", dashProject)))
+			return nil
+		},
+	}
+
+	DashCmd.AddCommand(pingCmd)
+}

src/client/acontext-cli/cmd/dash_projects.go

@@ -12,6 +12,14 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// printSetupComplete prints the common message after a project is configured.
+func printSetupComplete() {
+	fmt.Println("API key saved to ~/.acontext/credentials.json")
+	fmt.Println()
+	fmt.Println("Verify connectivity:")
+	fmt.Println("  acontext dash ping")
+}
+
 func init() {
 	projectsCmd := &cobra.Command{Use: "projects", Short: "Manage projects (requires login)"}
 
@@ -98,9 +106,7 @@ func init() {
 						return fmt.Errorf("save project key: %w", err)
 					}
 					fmt.Printf("Default project set to: %s\n", projectFlag)
-					fmt.Println("API key saved locally.")
-					fmt.Println()
-					fmt.Println("Setup complete. You can now use 'acontext dash' commands.")
+					printSetupComplete()
 					return nil
 				}
 
@@ -114,9 +120,8 @@ func init() {
 						return fmt.Errorf("rotate project key: %w", err)
 					}
 					fmt.Printf("Default project set to: %s\n", projectFlag)
-					fmt.Println("New API key generated and saved locally.")
-					fmt.Println()
-					fmt.Println("Setup complete. You can now use 'acontext dash' commands.")
+					fmt.Println("New API key generated.")
+					printSetupComplete()
 					return nil
 				}
 
@@ -136,9 +141,7 @@ func init() {
 					return fmt.Errorf("save project key: %w", err)
 				}
 				fmt.Printf("Default project set to: %s\n", projectFlag)
-				fmt.Println("API key saved locally.")
-				fmt.Println()
-				fmt.Println("Setup complete. You can now use 'acontext dash' commands.")
+				printSetupComplete()
 				return nil
 			}
 
@@ -157,7 +160,7 @@ func init() {
 				return fmt.Errorf("save project key: %w", err)
 			}
 			fmt.Println(tui.RenderSuccess(fmt.Sprintf("Default project set to: %s", choice.Name)))
-			fmt.Println(tui.RenderInfo("API key saved locally."))
+			printSetupComplete()
 			return nil
 		},
 	}
@@ -223,24 +226,22 @@ func init() {
 			}
 
 			// 2. Link project to org via Supabase RPC
-			if err := auth.LinkProjectToOrg(dashAccessToken, orgID, name, project.ID); err != nil {
+			if err := auth.LinkProjectToOrg(dashAccessToken, orgID, name, project.ProjectID); err != nil {
 				return fmt.Errorf("link project to organization: %w", err)
 			}
 
 			if dashJSON {
 				return output.RenderJSON(project)
 			}
-			fmt.Printf("Project created: %s (%s)\n", name, project.ID)
+			fmt.Printf("Project created: %s (%s)\n", name, project.ProjectID)
 
 			// Auto-save API key and set as default
 			if project.SecretKey != "" {
-				if err := auth.SetProjectKey(project.ID, project.SecretKey); err == nil {
-					fmt.Println("API key saved locally.")
+				if err := auth.SetProjectKey(project.ProjectID, project.SecretKey); err == nil {
+					_ = auth.SetDefaultProject(project.ProjectID)
+					fmt.Printf("Default project set to: %s\n", project.ProjectID)
+					printSetupComplete()
 				}
-				_ = auth.SetDefaultProject(project.ID)
-				fmt.Printf("Default project set to: %s\n", project.ID)
-				fmt.Println()
-				fmt.Println("Setup complete. You can now use 'acontext dash' commands.")
 			}
 			return nil
 		},
@@ -287,10 +288,8 @@ func init() {
 				return output.RenderJSON(stats)
 			}
 			fmt.Printf("Sessions:  %d\n", stats.SessionCount)
-			fmt.Printf("Messages:  %d\n", stats.MessageCount)
-			fmt.Printf("Disks:     %d\n", stats.DiskCount)
+			fmt.Printf("Tasks:     %d\n", stats.TaskCount)
 			fmt.Printf("Skills:    %d\n", stats.SkillCount)
-			fmt.Printf("Users:     %d\n", stats.UserCount)
 			return nil
 		},
 	}