Authenticate User

Sign up a new user or log in a returning user to Kite Passport. This skill is a prerequisite for all other Passport skills (request-session, x402-execute, wallet-send).

Reference files (read when you need exact detail):

• @references/commands.md — full command reference: every flag, validation rule, and JSON output shape for signup init, signup poll, signup exchange, login init, login verify, logout, and me, plus the exhaustive Error Handling reference and Input Validation Checklist.
• @references/examples.md — complete worked examples (new user signup, returning user login, login fallback to signup).

Step 0: Ensure CLI is Installed — MANDATORY

CRITICAL: Before running ANY kpass command, you MUST run the setup script first. This is NOT optional. Do not skip this step. Do not run any kpass command before setup completes successfully.

bash <skill-directory>/scripts/setup.sh

Where <skill-directory> is the directory containing this SKILL.md file (e.g., the directory this skill is installed in).

This script ensures kpass is installed and available on PATH. It will attempt to install it automatically if not found.

If setup succeeds (status: "ok" in JSON output): proceed to the next step.

If setup fails (status: "error"): STOP immediately. Show the user the error message and the installation instructions from the setup output. Do NOT search for the binary elsewhere. Do NOT try to build from source. Do NOT look in other directories. Just show the error and ask the user to install the CLI manually.

When to Use This Skill

• The user says "sign up", "create an account", "register", or similar.
• The user says "sign in", "log in", "authenticate", or similar.
• The user says "log out", "sign out", or similar.
• Any other skill returns exit code 3 (auth error) with a message like "Not logged in" or "JWT is expired".
• You need to check who is currently logged in.

Defaults (Do Not Ask the User Unless They Specify Otherwise)

Note on next_command: The CLI's next_command field may show kpass signup init or kpass login init without --client agent. You must still add --client agent when running it. The Defaults table above is authoritative; CLI hints are starting points, not literal commands.

Display Cards — MANDATORY

CRITICAL: You MUST display the formatted status cards shown in this skill after every major step. This is NOT optional. Never skip, summarize, or replace these cards with plain text. The exact horizontal-rule format must be used every time — no exceptions.

If a command succeeds and has a display card template below, you MUST output that card before doing anything else. Do not proceed to the next step until the card is displayed.

Where the login is saved

With a global install, kpass keeps one login in the home folder (.kite-passport/ there) and uses it from every folder, so run kpass me before asking for a new code. With a local (project) install, each project keeps its own login in its .kite-passport/ folder.

Decision: Login vs Signup

If the user says "sign in" or "authenticate" without specifying whether they have an existing account:

1. Try login first with login init.
2. If the command fails with exit code 4 (not found / "email not registered"), fall back to signup init.
3. If the user explicitly says "sign up", "create account", "register", or similar, go directly to signup init — do not try login first.

If the user explicitly asked to sign up/create/register and signup init fails because the email is already registered (error message contains "already registered"): the user's stated intent was a new account, not access to an existing one — do not silently switch to login init on their behalf. Ask them to choose, e.g. "An account already exists for {email}. Do you want me to log you into that account, or would you rather use a different email to create a new one?" Only run login init if they choose to log in; if they give a different email, retry signup init with it. See "Signup blocked — email already registered" in @references/commands.md for the full recovery steps.

After signup exchange succeeds, the user is fully authenticated. The signup exchange command returns a JWT and saves it to local config. Do NOT run login init after signup — it is unnecessary and will generate a conflicting OTP code.

Messaging After signup init — MANDATORY

CRITICAL: Do not present "click the verification link" and "share the sign-up code" as two independent, equally-valid ways to finish ("whichever is easier"). They are not alternatives. For a brand-new signup, signup exchange fails with "signup session not verified" until the link has been opened — the click is what marks the session verified server-side; the code only completes the exchange afterward. Pasting the code without opening the link first will not work, no matter how correct the code is.

CRITICAL: these are TWO SEPARATE emails, not one. signup init sends both at once, but they land as distinct messages with distinct subjects, and each has its own job. Never say "from the same email" or "that email" for the code — name the second email explicitly, or the user will go looking for an 8-character code inside the verification-link email and not find one.

Tell the user, in this order, right after signup init succeeds:

1. "Check {email} for an email titled 'Sign in to Kite Passport' and click the verification link in it — that confirms your address."
2. "For a new account, that link takes you to a 'Create a passkey' page — go ahead and create one there; it's part of finishing registration and you'll need it later to approve spending sessions and agent bindings." Say this proactively, before they click, not as a surprise afterward.
3. "You'll also get a second, separate email titled 'Your Kite Passport sign-up code' — that one has the 8-character code I still need from you to finish logging you in. Once you've clicked the link above, copy that code from the second email and paste it here."

Immediately after sending that message, start polling in the background — do not wait for the user to say "verified" or otherwise nudge you. Launch, as a background command (run_in_background):

kpass signup poll --signup-id <signup_id> --wait --output json

This blocks server-side for up to --timeout (default 600s) until the link is clicked, so it must run in the background, not inline — an inline call would stall the whole conversation for up to ten minutes. The point of running it at all is that the user should never have to manually tell you they clicked the link: the background job's own completion is that signal. When it comes back verification_status: "verified", say so ("✅ email confirmed") and, if the code hasn't arrived yet, remind the user you're still waiting on it — do not silently sit on the confirmation. If the user pastes the code before this background poll has resolved, do not run signup exchange yet — first confirm the link was opened (check the poll's result, or a one-shot signup poll without --wait), then run the exchange. See "Signup exchange fails with 'not verified'" in @references/commands.md for the exact recovery if you skip ahead and hit it anyway.

Security: Codes Are Passed via Environment Variable, Not a Flag

CRITICAL — do not paraphrase or weaken this. signup exchange and login verify both accept the one-time code via an environment variable rather than a CLI flag:

KPASS_SIGNUP_CODE=<CODE> kpass signup exchange --signup-id <signup_id> --output json
KPASS_LOGIN_CODE=<OTP_CODE> kpass login verify --login-id <login_id> --output json

Always use the env-var form (KPASS_SIGNUP_CODE, KPASS_LOGIN_CODE) — never the --code flag. Environment variables are not visible in process listings (ps, /proc/<pid>/cmdline), while flags are. The --code flag still works for backward compatibility but is discouraged; do not default to it. This applies every time you re-run signup exchange or login verify (e.g., after a wrong-code retry), not just the first attempt. See @references/commands.md for the full argument tables for both commands.

Display Cards: Account Created / Welcome Back

MANDATORY — After signup exchange succeeds, you MUST display this card. Do not skip this. Do not summarize. Do not replace with plain text:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 Account Created & Logged In!

📧 Email:    {email}
🆔 User ID:  {user_id}
🔓 Session active
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

MANDATORY — After login verify succeeds, you MUST display this card. Do not skip this. Do not summarize. Do not replace with plain text:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
👋 Welcome back!

📧 {email}
🆔 {user_id}
🔓 Session active
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

You MUST always display the matching card after a successful response. No exceptions. Fill in all placeholders from the JSON output. See @references/commands.md for the full success JSON shape these placeholders are pulled from, and @references/examples.md for both cards shown in context.

Error Handling

See @references/commands.md for the exact JSON error envelope of every command and the full Specific Error Scenarios reference (wrong OTP, expired verification link, already-consumed signup session, email not registered).

Commands That DO NOT Exist

Do NOT attempt any of the following. They will fail:

• kpass signup (without a sub-command) -- must use signup init, signup poll, or signup exchange
• kpass login (without a sub-command) -- must use login init or login verify
• kpass signup verify -- does not exist; signup uses exchange with KPASS_SIGNUP_CODE env var (or --code flag)
• kpass login poll -- does not exist; login uses verify with KPASS_LOGIN_CODE env var (or --code flag), not polling
• kpass login exchange -- does not exist
• kpass register -- does not exist; use signup init for user registration
• kpass auth -- does not exist
• kpass signin -- does not exist; use login init
• Any command with --json -- the correct flag is --output json (two separate tokens)
• Any command with --interactive -- the correct flag is --no-interactive
• Any command with --exchange-token -- this flag was removed; use KPASS_SIGNUP_CODE env var (or --code flag) instead

Cross-Skill References

After Successful Authentication (what to do next)

Once the user is logged in, immediately resume the task that required authentication:

• If the original task involves shopping or buying products: Invoke the shopping skill.
• Right after sign-up or log-in, check the account allowance: kpass allowance status --output json (free). If state is none, offer once to set one up at its dashboard_url: paid calls inside the allowance then need no approval. The rules are in the kite-passport skill, "How the Account Allowance Works".
• If the original task involves a paid API or service: go to x402-execute; it pays from the account allowance with no session step and no question. Use request-session only when the CLI says the allowance can't pay or the user asks for a separate spending session.
• If the original task involves sending tokens or checking balance: Invoke the wallet-send skill.
• If the user just wanted to log in: Confirm success and mention available capabilities: "You're logged in. I can now shop for products, make payments, transfer tokens, or check your account activity."
• To check whether the user is logged in, run kpass me --output json. There is no kpass whoami.

Related Skills

• To register the agent and create a spending session, use the request-session skill.
• To make direct wallet transfers (no session needed) or request test tokens from the faucet, use the wallet-send skill.
• To execute x402 paid API requests through a session, use the x402-execute skill.
• To inspect registered agents and session history, use the manage-agents skill.