feat(cli): Improve error message when authentication is required (#80)

[bhardwajparth51]

What does this PR do?

When a user's session cookie is invalid or expired, the Appwrite CLI currently shows a raw API error:

✗ Error: User (role: guests) missing scopes (["projects.read"])

This PR intercepts 401 general_unauthorized_scope errors where the role is guests directly inside Client.call() in templates/cli/lib/client.ts, and replaces the cryptic error with a clear, actionable message:

✗ Error: Login is required. Run 'appwrite login'.

This applies generically to any API endpoint (/teams, /databases, /functions, etc.) — not just /projects — since the root cause is always the same: an invalid or expired session.

Test Plan

1. Regenerate the CLI SDK:

   docker run --rm -v $(pwd):/app -w /app php:8.3-cli php example.php cli

2. Build the CLI:

   cd examples/cli && npm i && npm run build:runtime

3. With an invalid or expired session, run any CLI command that requires authentication and verify the output is:

   ✗ Error: Login is required. Run 'appwrite login'.
   

   instead of the raw API error message.

Related PRs and Issues

• Fixes 🚀 Feature: Improve Error Message when Authentication is Required sdk-for-cli#80

Have you read the Contributing Guidelines?

Yes.

Summary by CodeRabbit

• Bug Fixes
  • Improved error handling for 401 authorization errors related to guest scope issues. Users now receive clearer, more actionable login prompts instead of generic error messages, enabling faster resolution of authentication problems.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a runtime check in the CLI client to detect 401 JSON errors of type general_unauthorized_scope indicating a guest role and throws an AppwriteException instructing the user to run the CLI login command using the exported EXECUTABLE_NAME constant.

Changes

Cohort / File(s)	Summary
Client runtime check templates/cli/lib/client.ts	Adds a branch that detects 401 errors with type: general_unauthorized_scope and a message indicating a guest role, then throws an AppwriteException with a login instruction referencing EXECUTABLE_NAME before the generic error path.
Constants export templates/cli/lib/constants.js	Exports new EXECUTABLE_NAME constant for composing the user-facing login guidance message.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hopped through code, a tiny guide,
Found guests at the gate, with nowhere to hide.
"Please login," I whisper, with carrot and name,
EXECUTABLE_NAME lights the path, clear and tame.
Hooray for clearer errors — a hopping good change! 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and clearly summarizes the main change: improving the error message when authentication is required in the CLI.
Linked Issues check	✅ Passed	The PR successfully addresses issue #80 by intercepting 401 errors with type general_unauthorized_scope and displaying a user-friendly login message instead of the technical scope error.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to addressing issue #80: adding authentication error detection and improving the error message for guest users with invalid sessions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[bhardwajparth51]

@ChiragAgg5k would appreciate a review when you get a chance!

[ChiragAgg5k]

@bhardwajparth51 please check the comments + would really appreciate a screenshot of the error message working

[coderabbitai]

🧹 Nitpick comments (1)

templates/cli/lib/client.ts (1)

244-248: Add a regression test to catch upstream message wording changes.

Since Appwrite doesn't expose a machine-readable field to distinguish general_unauthorized_scope caused by guest/expired session, the regex check on json.message is the only documented approach. However, this creates a fragility: any wording change upstream silently breaks the guest error path and resurfaces the raw scope error. Lock this in with a test that verifies the matcher catches the expected message format.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@templates/cli/lib/client.ts` around lines 244 - 248, Add a regression test
that ensures the isUnauthorized matcher (the code building the isUnauthorized
boolean in templates/cli/lib/client.ts using json.code, json.type, and the regex
/role:\s*guests/i against json.message) still matches the expected Appwrite
guest/expired-session message format; create a unit test that constructs JSON
responses with realistic message strings (including variations in spacing and
casing) and asserts isUnauthorized === true, and include one negative case to
ensure other messages do not match so future upstream wording changes fail the
test rather than silently breaking the guest error path.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@templates/cli/lib/client.ts`:
- Around line 244-248: Add a regression test that ensures the isUnauthorized
matcher (the code building the isUnauthorized boolean in
templates/cli/lib/client.ts using json.code, json.type, and the regex
/role:\s*guests/i against json.message) still matches the expected Appwrite
guest/expired-session message format; create a unit test that constructs JSON
responses with realistic message strings (including variations in spacing and
casing) and asserts isUnauthorized === true, and include one negative case to
ensure other messages do not match so future upstream wording changes fail the
test rather than silently breaking the guest error path.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d86ed1b1-e5e6-466a-a142-d53db914b4d5

📥 Commits

Reviewing files that changed from the base of the PR and between 6a1aa67 and 83367a7.

📒 Files selected for processing (1)

• templates/cli/lib/client.ts

[bhardwajparth51]

Done! Renamed isGuestUnauthorized to isUnauthorized and updated the error message to You are not authenticated. Run 'appwrite login' to authenticate and try again.

The general_unauthorized_scope error requires a live Appwrite session with invalid/expired credentials to trigger — the CLI intercepts at the config level before the API call when no session exists at all, making it difficult to reproduce locally.

Here's a simulation of the exact detection logic and output: