Asiyst CLI

The asiyst CLI connects a website that uses @asiyst/sdk to an Asiyst project. It does not render the avatar, chatbot, dashboard, or analytics UI.

Installation and Execution

Global Installation

To use asiyst as a global command:

npm install --global @asiyst/cli
# or with Bun:
bun add -g @asiyst/cli

# Run:
asiyst --version
asiyst connect

Project-Local Installation

To install @asiyst/cli inside a specific project:

npm install --save-dev @asiyst/cli
# or with Bun:
bun add -d @asiyst/cli

Supported project-local invocations:

• npx:

  npx asiyst --version
  

• Binary shim:

  # macOS / Linux:
  ./node_modules/.bin/asiyst --version
  
  # Windows PowerShell:
  .\node_modules\.bin\asiyst --version
  
  # Windows CMD:
  node_modules\.bin\asiyst --version
  

• npm scripts: In package.json:

  "scripts": {
    "asiyst": "asiyst"
  }
  

  Then run:

  npm run asiyst -- status
  

• Bun:

  bunx asiyst --version
  

On-Demand Execution

npx @asiyst/cli@latest

Commands

The Asiyst CLI behaves like a standard developer tool (such as Git or Supabase CLI). Running asiyst with no arguments displays concise usage information and exits. Each operation is invoked directly as asiyst <command>.

Use asiyst connect --project-id <PROJECT_ID> or asiyst connect to start the authentication and project connection flow. Without --project-id, the authenticated flow uses an arrow-key selector to choose an existing project or create a new one through the secure web handoff, then asks for the public Project ID. The CLI never prompts for a User ID or substitutes the authenticated account ID for a project ID.

Standard commands are login, logout, connect, disconnect, status, project, avatar, sdk, verify, doctor, health, config, update, and restart.

asiyst restart checks the latest available version on npm for the CLI itself, compares semantic versions, prompts for confirmation, safely installs the update for the active environment (global/npx/local), verifies the installed version, and restarts the CLI process automatically while preserving all existing credentials and preventing restart loops.

asiyst sdk displays the status of @asiyst/sdk installed in the current project (declared, installed, latest published npm version). asiyst sdk update checks npm registry for the latest @asiyst/sdk, detects the project package manager (npm, pnpm, yarn, bun), prompts for confirmation, updates @asiyst/sdk in the target project/workspace, and verifies node_modules/@asiyst/sdk/package.json.

asiyst login checks the existing CLI session with the authenticated session endpoint before acting. A valid session is reused without opening the browser; an expired or rejected session is cleared and replaced through browser authorization. If the API cannot be reached, the existing session is preserved and login reports that it could not be verified. With no valid session, browser authorization uses a randomly assigned localhost callback: the CLI registers the callback and state with POST /cli/auth/challenge, opens the returned Asiyst authorization URL, validates the one-time callback code and state, consumes the challenge, and securely stores the verified CLI session. Approval in the browser alone is not treated as a successful login. No User ID, project ID, or API key is requested by login.

asiyst connect --project-id K8mP2xQ7_vL4N9cR5T1zB6Y3
asiyst status
asiyst avatar import --avatar-id A7K9M2QX4P
asiyst disconnect

The connection flow verifies the authenticated account, selected 24-character Project ID, API key, and selected 10-character Avatar ID. The API verifies that the account, key, selected project, and avatar belong together before the connection is saved. Use asiyst connect --project-id <PROJECT_ID> --avatar-id <AVATAR_ID> to bypass project selection and provide both IDs non-interactively; otherwise the CLI opens the relevant dashboard pages and prompts for them. Invalid project IDs can be corrected and retried, while expired sessions and unauthorized projects report actionable errors.

Avatar verification uses the approved CLI contract. Avatar import is currently blocked after verification because the approved contract does not specify the asset upload or file-reference mechanism. The CLI does not send an incomplete import request or modify website files while that information is missing.

GitHub is not part of this CLI flow. GitHub repository authorization and Knowledge Base configuration are managed by Asiyst Web and Supabase. The web dashboard may connect a Knowledge Base to an avatar, but asiyst avatar import does not request GitHub credentials, download repository content, or block an import when GitHub is not connected. The website only receives the SDK integration; the avatar retrieves configured knowledge through the Asiyst backend.

The separation is:

GitHub repository
  -> Asiyst Knowledge Base
  -> Avatar knowledge configuration
  -> Asiyst backend
  -> @asiyst/sdk
  -> Website visitor

The CLI connection flow proceeds as:

Step 1: Authenticated account
  -> Step 2: Existing project selection or secure project creation / verification
  -> Step 3: Domain verification
  -> Step 4: API key verification
  -> Step 5: SDK install & setup
  -> Step 6: Avatar configuration & import
  -> Step 7: Knowledge source connection
  -> Final verification

Interactive startup performs a lightweight npm version check. If a newer release exists, the CLI only displays a notification. It never installs or restarts automatically; run update and confirm to install it. Global installations are updated in place. For npx invocations, the latest package is downloaded and verified for that invocation without changing the website project.

The CLI uses canonical /api/v1/cli/... paths for API-key verification, owner status, avatar verification, and knowledge operations described by docs/sdk-cli-contract.md. Other existing login, onboarding, project-selection, and diagnostic operations have not yet been compared with the Web-published contract. Passwords, AI provider keys, Supabase keys, and private API credentials must never be placed in URLs or logged.

The CLI creates a persistent onboarding session with POST /cli/onboarding/session using the authenticated CLI session. Browser pages are opened through POST /cli/onboarding/handoff, authenticated with that reference in request headers. The response must contain a short-lived, single-use handoffToken; only that token is placed in https://asiyst.com/cli/onboarding/handoff?token=.... The web handoff endpoint must validate and consume the token, establish the existing web session for its verified user, and redirect directly to the requested page (for example /project/new) without routing through /register. Invalid or expired sessions must return SESSION_EXPIRED, so the CLI can ask the user to reconnect rather than silently restarting registration.

Production API defaults to https://nqhxpgsjofzqudyqkqib.supabase.co/functions/v1/api.

Contract and limitations

The local approved design is documented in docs/ASIYST_API_Contract_v1_for_approval.md; it is not yet a code-accurate Web-published contract. Before staging, compare it against the Web-published contract and document differences. Avatar import additionally requires the Web team to specify the actual upload or file-reference mechanism.

Development

npm run build
npm test
npm pack --dry-run