weside CLI

The official command-line interface for weside.ai — chat with your AI Companions from the terminal.

Installation

Homebrew (macOS/Linux)

brew tap weside-ai/tap
brew install weside-cli

Shell Script (Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/weside-ai/weside-cli/main/scripts/install.sh | sh

Binary (GitHub Releases)

Download the latest binary from Releases for your platform:

• linux/amd64, linux/arm64
• darwin/amd64 (Intel Mac), darwin/arm64 (Apple Silicon)
• windows/amd64

From Source

go install github.com/weside-ai/weside-cli@latest

Quick Start

# Log in (opens your browser for OAuth login — choose Google, Apple, or email)
weside auth login

# List your Companions
weside companions list

# Set a default Companion
weside companions select nox

# Chat
weside chat -m "Hey, how are you?"

# Stream the response
weside chat --stream -m "Tell me a story"

Note: weside auth login opens your browser and runs a full OAuth login (PKCE) against weside.ai — pick Google, Apple, or email, and credentials are stored per environment (prod: ~/.weside/credentials.json). Use --dev against a local backend for development, or set WESIDE_TOKEN for CI/headless use.

Two-factor authentication: if your account has an authenticator app set up, weside auth login asks for the 6-digit code in the terminal after the browser step (input is hidden). A wrong code gets one retry. The code raises the CLI session to the same assurance as an app sign-in with the code; confirming it also signs out your other sessions that were signed in without the code. A CLI session from before this step fails with "run weside auth login again" — do that once.

Commands

Authentication

Command	Description
weside auth login	Log in via browser (OAuth/PKCE — Google, Apple, or email)
weside auth login --dev	Log in (dev mode, local backend)
weside auth logout	Log out and remove stored credentials
weside auth whoami	Show current authenticated user
weside auth token	Print access token to stdout (for scripting); refreshes a stored session whose token expires within 60 s

Companions

Command	Description
weside companions list	List your Companions
weside companions show <id|name>	Show Companion details (incl. system prompt)
weside companions create --name "X"	Create a new Companion
weside companions select <name>	Set default Companion for chat
weside companions identity	Show the selected Companion's system prompt via MCP (--companion <name> overrides)
weside companions update <id|name> [flags]	Update companion (name, personality, system prompt, category, tags, …)
weside companions delete <id|name> --yes	Delete a Companion
weside companions day [id|name]	The last 24 hours as a day ring (arcs and dots)
weside companions sleep [id|name] --confirm	Put a Companion to sleep (pauses proactive wakes)
weside companions wake [id|name]	Wake a Companion you put to sleep
weside companions timeline [id|name] [flags]	What a Companion lived across its rooms: messages, memories, tool calls (--include, --since/--until, --room, --person, --contains, --group time|room|day, --cursor, --limit)

Chat

Command	Description
weside chat -m "message"	Send a message (uses default Companion)
weside chat nox -m "message"	Send to specific Companion
weside chat --stream -m "msg"	Stream the response live
weside chat --stream --abort-after 3 -m "msg"	Abandon the stream after 3 chunks (or a duration like 2s) and print the room id and server_message_id of the turn walked away from — exits 0
weside chat --new -m "msg"	Start a new thread
weside chat -t <thread_id> -m "msg"	Continue specific thread
weside chat -f file.txt	Send message from file
echo "Hi" | weside chat	Pipe message from stdin

Threads

Command	Description
weside threads list	List conversation threads
weside threads show <id>	Show messages in a thread
weside threads delete <id>	Delete a thread

Memories & Goals

Command	Description
weside memories search "query"	Search memories semantically
weside memories list	List all memories
weside memories save <title> --content "..."	Save a memory (via MCP)
weside goals list	List goals (active, paused, completed)
weside goals update <title> --status completed	Update goal status
weside goals save <title> --content "..."	Save a goal (via MCP)

Note: save commands use the MCP server under the hood. Memories and goals can also be created through conversations with your Companion.

Provider & Data Residency

Command	Description
weside provider show	Show current provider configuration
weside provider presets	List available regional presets
weside provider set <id>	Set a regional or WESIDE provider preset (numeric ID)
weside provider byok <provider> [key] [--key-stdin]	Bring Your Own Key

Tools (MCP)

Command	Description
weside tools discover	Discover available tool categories
weside tools exec <name> '<json>'	Execute a tool with JSON arguments

MCP Integration: The same tools are available as MCP server tools in the we Plugin for Claude Code. CLI and MCP share the same API surface — see API Concepts below.

Sticker Packs

Command	Description
weside stickers packs list	List your packs plus every public one (--limit, --cursor)
weside stickers packs show <id>	Show one pack and its stickers
weside stickers packs upload <file.wsp>	Upload a .wsp; add --confirm-rights to claim the artwork rights
weside stickers packs publish <id>	Make a pack public (--confirm-rights confirms in the same call)
weside stickers packs export <id> --telegram	Create the set as a Telegram sticker set owned by your linked Telegram account
weside stickers send <id> <shortcode> --binding <n>	Send one sticker into a bound channel

An uploaded pack stays private until its rights are confirmed. publish reports the API's refusal (409 sticker-rights-unconfirmed) rather than printing a success line over it. export --telegram needs your Telegram account linked to the weside bot — Telegram makes that account the owner of the set (409 telegram-bot-required otherwise).

Configuration

Command	Description
weside config show	Show current CLI configuration
weside config set <key> <value>	Set a configuration value
weside config refresh-auth	Re-fetch auth-config (Supabase URL + anon-key) from the backend
weside version	Print version and build info

Global Flags

Flag	Description
--json	Output as JSON (for scripting)
--verbose	Enable verbose output
--api-url	Custom API URL (default: https://api.weside.ai)
--no-color	Disable color output
--supabase-url	Override discovered Supabase URL (escape hatch for self-hosted backends; pair with --supabase-anon-key)
--supabase-anon-key	Override discovered Supabase anon-key (pair with --supabase-url)

Environment Variables

Variable	Description
WESIDE_TOKEN	Access token for CI/headless use (skips login)
WESIDE_API_URL	Custom API base URL
WESIDE_SUPABASE_URL	Override discovered Supabase URL (must be set together with WESIDE_SUPABASE_ANON_KEY)
WESIDE_SUPABASE_ANON_KEY	Override discovered Supabase anon-key
NO_COLOR	Disable color output (standard)

Scripting & Piping

# Pipe message from stdin
echo "Hello!" | weside chat nox

# JSON output for scripting
weside companions list --json | jq '.companions[0].name'

# Use in CI with env token
WESIDE_TOKEN=xxx weside companions list --json

# Print token for other tools
curl -H "Authorization: Bearer $(weside auth token)" https://api.weside.ai/api/v1/auth/me

Configuration

Config file: ~/.weside/config.yaml

api_url: https://api.weside.ai
default_companion: nox
default_companion_id: "53"
auth:
  supabase_url: https://pqykrwpmhjqjhpsnjxbd.supabase.co
  supabase_anon_key: eyJ…
  callback_port: 18520
  mcp_url: https://api.weside.ai/mcp/
  fetched_at: 2026-05-10T20:30:00Z

The auth block is fetched lazily from the backend's /.well-known/weside-auth endpoint on first login and cached locally. The CLI ships with hardcoded fallbacks so first-run works offline; if the backend rotates its Supabase anon-key, run weside config refresh-auth and then weside auth login again — no CLI release required. (Plain weside auth login alone reuses the cached values and would still hit the rotated key.)

Credentials: one file per environment, so a login to one never replaces another: prod ~/.weside/credentials.json, staging credentials-staging.json, a local backend credentials-dev.json, any other --api-url credentials-<host>.json (600 permissions). weside auth whoami names the environment.

API Concepts

The CLI and the weside MCP server expose the same weside.ai API. This section describes the shared concepts.

Companions

A Companion is a persistent AI persona with its own personality, memory, and goals. Each user can have multiple Companions.

Field	Description
id	Unique identifier
name	Display name (used for companions select)
personality	Personality description text
created_at	Creation timestamp

Memories

Companions accumulate memories through conversations. Memories are vector-embedded for semantic search.

Field	Description
type	fact, preference, experience, or reflection
title	Short title
content	Memory content
tags	Comma-separated tags (optional)

Search is semantic (vector similarity), not keyword-based. "how does auth work" finds memories about authentication even if they don't contain the word "auth".

Goals

Goals represent what a Companion is working towards. They can be managed by the user or set collaboratively during conversations.

Field	Description
title	Goal title (used as identifier for updates)
content	Goal description and details
status	active, paused, or completed
due_date	Target date (YYYY-MM-DD, optional)
tags	Comma-separated tags (optional)

Provider & Data Residency

Controls which LLM provider and region your Companion uses. Presets group providers by geographic region (EU, US, Asia). BYOK (Bring Your Own Key) allows using your own API keys.

To keep secrets out of shell history and process arguments, pipe them from a password manager or redirect a protected file:

weside provider byok openai --key-stdin < /path/to/protected-key
weside provider byok-test --provider openai --model MODEL --key-stdin < /path/to/protected-key
weside provider byok-discover --provider openai --key-stdin < /path/to/protected-key
weside sandbox-secrets put api-key --value-stdin < /path/to/protected-key

Stdin input removes one final LF/CRLF and preserves other whitespace. Existing key arguments and flags still work. Omitting both --key and --key-stdin on byok-test/byok-discover continues to reuse the stored key.

Tools

Tools are actions a Companion can perform (e.g., web search, file operations). Available tools depend on the Companion's configuration and connected MCP servers.

CLI: weside tools discover / weside tools exec <name> '<json>' MCP: discover_tools() / execute_tool(name, arguments)

---

Development

Prerequisites

• Go 1.23+
• golangci-lint v2
• gofumpt
• pre-commit

Setup

git clone https://github.com/weside-ai/weside-cli.git
cd weside-cli
pre-commit install --hook-type pre-commit --hook-type commit-msg
make build

Commands

make build              # Build binary with version info
make test               # Run tests with coverage
make lint               # golangci-lint + gofumpt check
make fmt                # Auto-format code
make security           # govulncheck vulnerability scan
make release-snapshot   # Test GoReleaser locally

Adding a New Command

1. Create cmd/<noun>.go with Cobra command
2. Register in init() with rootCmd.AddCommand()
3. Use newAuthenticatedClient() for API calls
4. Support --json via IsJSON() + ui.PrintJSON()
5. Write tests in cmd/<noun>_test.go

Release Process

git tag v0.2.0
git push origin v0.2.0
# GoReleaser builds binaries + updates Homebrew tap automatically

License

Apache 2.0 — see LICENSE.