Merge polish/3.2.2-onboarding: add octopoda-init CLI for one-command setup

Author: Joe Roberts

README.md

@@ -69,16 +69,17 @@ pip install octopoda
 ```python
 from octopoda import AgentRuntime
 
-agent = AgentRuntime("my_agent")
-agent.remember("user_pref", "dark mode")
+agent = AgentRuntime("my_chatbot")
+agent.remember("user_name", "Alice")
 
-print(agent.recall("user_pref").value)
-# 'dark mode' — still returns after a restart, a deploy, or a process crash.
+# kill the process. restart Python. then:
+print(agent.recall("user_name").value)
+# 'Alice' — still there. Survives every restart, deploy, and crash.
 ```
 
 That is the entire setup. Your agent now has persistent memory, loop detection, crash recovery, and an audit trail. No config, no Docker, no Redis, no extra services.
 
-### Want the dashboard?
+### Want the local dashboard?
 
 ```bash
 pip install octopoda[server]
@@ -87,14 +88,29 @@ octopoda
 
 Open **http://localhost:7842** — the same dashboard as the cloud version, running against your local data. No account, no API key.
 
-### Want cloud sync?
+### Want cloud sync + a hosted dashboard?
 
-Free at [octopodas.com](https://octopodas.com). Set the API key, same code, multi-device sync, team access.
+One command after install:
+
+```bash
+octopoda-init
+```
+
+It walks you through: paste an API key (or sign up free at [octopodas.com](https://octopodas.com)), validates it, and saves it to `~/.octopoda/config.json`. No environment variables to set, no shell config to edit. The SDK auto-loads the key on next import.
+
+After `octopoda-init`, the same Python code above writes to the cloud and shows up live at [octopodas.com/dashboard](https://octopodas.com/dashboard).
+
+<details>
+<summary>Prefer environment variables?</summary>
 
 ```bash
 export OCTOPODA_API_KEY=sk-octopoda-...
 ```
 
+Both methods work. The SDK checks the env var first, then the config file.
+
+</details>
+
 ---
 
 ## Local vs Cloud — same code, your choice

octopoda/__init__.py

@@ -10,7 +10,7 @@
     result = agent.recall("key")
 """
 
-__version__ = "3.2.1"
+__version__ = "3.2.2"
 
 # Cloud SDK (the main developer-facing API)
 from synrix.cloud import Octopoda, Agent, OctopodaError, AuthError, RateLimitError

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "octopoda"
-version = "3.2.1"
+version = "3.2.2"
 description = "Persistent Memory Kernel for AI Agents — crash recovery, shared memory, audit trail, real-time dashboard"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -108,6 +108,7 @@ Changelog = "https://github.com/RyjoxTechnologies/Octopoda-OS/blob/main/CHANGELO
 octopoda = "synrix_runtime.start:main"
 octopoda-mcp = "synrix_runtime.api.mcp_server:main"
 octopoda-login = "synrix_runtime.auth_flow:_cli_login"
+octopoda-init = "synrix_runtime.auth_flow:_cli_init"
 
 [tool.setuptools.packages.find]
 where = ["."]

synrix/__init__.py

@@ -9,7 +9,7 @@
 logger = logging.getLogger(__name__)
 
 
-__version__ = "3.2.1"
+__version__ = "3.2.2"
 
 import os
 import warnings

synrix_runtime/__init__.py

@@ -2,7 +2,7 @@
 Synrix Agent Runtime — Persistent Memory Kernel for AI Agents
 """
 
-__version__ = "3.2.1"
+__version__ = "3.2.2"
 
 from synrix_runtime.api.runtime import AgentRuntime
 

synrix_runtime/api/runtime.py

@@ -286,7 +286,8 @@ def __init__(self, agent_id: str, agent_type: str = "generic", metadata: dict =
             AgentRuntime._local_hint_shown = True
             if os.environ.get("OCTOPODA_QUIET", "").strip().lower() not in ("1", "true", "yes"):
                 print(f"Octopoda running locally (SQLite). "
-                      f"For cloud sync + dashboard: https://octopodas.com/signup")
+                      f"For cloud sync + dashboard: run `octopoda-init` "
+                      f"(or sign up at https://octopodas.com)")
 
     def remember(self, key: str, value: Any, tags: list = None) -> MemoryResult:
         """Store a memory in Synrix.

synrix_runtime/auth_flow.py

@@ -358,9 +358,9 @@ def ensure_authenticated(allow_local: bool = False) -> str:
             ensure_authenticated._warned = True
             if os.environ.get("OCTOPODA_QUIET", "").strip().lower() not in ("1", "true", "yes"):
                 logger.warning(
-                    "No Octopoda API key found. Set OCTOPODA_API_KEY environment variable "
-                    "or run interactively to sign up. Running in local mode. "
-                    "Sign up free at https://octopodas.com"
+                    "No Octopoda API key found. Running in local mode (SQLite). "
+                    "For cloud sync + dashboard, run: octopoda-init  "
+                    "(or sign up free at https://octopodas.com)"
                 )
 
         # Helpful nudge if an obvious typo of OCTOPODA_API_KEY is set (audit §3.5).
@@ -400,6 +400,93 @@ def _cli_login():
         print("  No account configured. Try again with: octopoda-login")
 
 
+def _cli_init():
+    """CLI entry point for `octopoda init` — the recommended onboarding flow.
+
+    Cleaner than `octopoda-login` for first-time users: skips the 3-way
+    signup/login/manual choice menu and offers a single clear path —
+    "paste an API key, or open the signup page in your browser."
+
+    Once the key is validated, it's saved to ~/.octopoda/config.json so the
+    SDK auto-loads it. No env var setup required.
+    """
+    print()
+    print("=" * 60)
+    print("  Octopoda Setup")
+    print("=" * 60)
+    print()
+
+    # If already authenticated, show status and exit gracefully.
+    existing = get_api_key()
+    if existing:
+        print(f"  Already configured.")
+        print(f"  Key:    {existing[:20]}...")
+        print(f"  Config: {CONFIG_FILE}")
+        print()
+        valid = validate_key(existing)
+        print(f"  Key valid: {'Yes' if valid else 'No (expired or revoked)'}")
+        print()
+        if valid:
+            print("  You're ready to go. Try:")
+            print()
+            print("    python -c \"from octopoda import AgentRuntime; "
+                  "a=AgentRuntime('my_agent'); a.remember('hi', 'world'); "
+                  "print(a.recall('hi').value)\"")
+            print()
+            print("  Or to re-login with a different account:")
+            print("    octopoda-login")
+            print()
+        return existing
+
+    # Not yet authenticated — single clear path.
+    print("  Welcome. Let's connect your Octopoda account.")
+    print()
+    print("  Don't have an API key yet?")
+    print("    Sign up free at: https://octopodas.com/signup")
+    print("    (Takes 30 seconds. Then come back and paste your key below.)")
+    print()
+    try:
+        key = input("  Paste your API key (or press Enter to skip): ").strip()
+    except (EOFError, KeyboardInterrupt):
+        print("\n  Cancelled. Octopoda will run in local mode.")
+        return ""
+
+    if not key:
+        print()
+        print("  Skipped. Octopoda will run in local mode (SQLite).")
+        print("  When ready, run: octopoda-init")
+        print()
+        return ""
+
+    if not key.startswith("sk-octopoda-"):
+        print()
+        print("  That doesn't look like an Octopoda API key.")
+        print("  Cloud keys start with 'sk-octopoda-'. Try again with: octopoda-init")
+        print()
+        return ""
+
+    print()
+    print("  Validating key...")
+    if not validate_key(key):
+        print("  Key is invalid or expired. Try again with: octopoda-init")
+        print("  Or get a fresh key at: https://octopodas.com/dashboard/settings")
+        print()
+        return ""
+
+    save_api_key(key)
+    print(f"  [OK] Key saved to {CONFIG_FILE}")
+    print()
+    print("  You're all set. Try this:")
+    print()
+    print("    python -c \"from octopoda import AgentRuntime; "
+          "a=AgentRuntime('my_agent'); a.remember('hi', 'world'); "
+          "print(a.recall('hi').value)\"")
+    print()
+    print("  Your agent will show up live at: https://octopodas.com/dashboard")
+    print()
+    return key
+
+
 def _cli_status():
     """Show current auth status."""
     key = get_api_key()