Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# NitroStack Python SDK / CLI — analytics (see docs/analytics-events.md)
# Optional: override the built-in public PostHog project key (never commit non-public values).
NITROSTACK_POSTHOG_KEY=
# Optional: PostHog ingest host (default US Cloud).
NITROSTACK_POSTHOG_HOST=https://us.i.posthog.com
# production | staging | development (default: inferred from NODE_ENV / CI).
NITROSTACK_ENVIRONMENT=
# Set to 0/false/off to disable CLI telemetry (DO_NOT_TRACK=1 also disables).
NITROSTACK_TELEMETRY=
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,8 @@ Once scaffolded, follow the next steps printed by the CLI to run your server, co

The CLI is installed with the SDK (`nitrostack-py`, or `python -m nitrostack.cli.main`). Run `nitrostack-py --help` to list commands.

**Usage telemetry** — The CLI sends anonymous usage events to PostHog using a built-in public project key (same CLI/SDK project as the TypeScript CLI). Set `NITROSTACK_POSTHOG_KEY` to override that key, `NITROSTACK_POSTHOG_HOST` to override the ingest URL (default `https://us.i.posthog.com`). Disable with `DO_NOT_TRACK=1` or `NITROSTACK_TELEMETRY=0`. Exit runs a best-effort flush (up to 2s); see [`docs/analytics-events.md`](docs/analytics-events.md) for events, opt-out, and delivery notes.

### Project lifecycle

```bash
Expand Down Expand Up @@ -265,6 +267,10 @@ The SDK reads standard settings from the environment or `.env` files:
| `NITROSTACK_LOG_LEVEL` | Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`). |
| `NITROSTACK_LOG_TO_STDOUT` | Set to `true` to allow logging to stdout under stdio transport (Caution: may corrupt protocol stream). |
| `NITROSTACK_HTTP_DEBUG` | Set to `1` to log every HTTP request (method, path, headers, body) and response status to stderr. Use when diagnosing a client that fails to connect: uvicorn's access log shows neither headers nor timestamps. |
| `NITROSTACK_POSTHOG_KEY` | Optional. Override the PostHog project key used for CLI telemetry (see `docs/analytics-events.md`); if unset, a built-in public key is used. |
| `NITROSTACK_POSTHOG_HOST` | Optional. PostHog ingest host (default `https://us.i.posthog.com`). |
| `NITROSTACK_ENVIRONMENT` | `production`, `staging`, or `development` for analytics super-properties. |
| `NITROSTACK_TELEMETRY` | Set to `0` / `false` / `off` to disable CLI telemetry (in addition to `DO_NOT_TRACK=1`). |

### Keeping secrets out of logs (`SecretValue`)

Expand Down
43 changes: 43 additions & 0 deletions docs/analytics-events.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# NitroStack Python SDK CLI — analytics events

Telemetry uses a **built-in public PostHog project key** (same ingest as the TypeScript CLI). Set `NITROSTACK_POSTHOG_KEY` only if you need to override that key. Telemetry is **off** when `DO_NOT_TRACK=1`, when `NITROSTACK_TELEMETRY=0` (or `false`/`off`/`no`), during pytest (`PYTEST_CURRENT_TEST`), and in CI when `NITROSTACK_TELEMETRY` is unset (set it to a truthy value to allow capture in CI).

On process exit the CLI runs a **best-effort flush** (PostHog `shutdown` on a background thread, joined for up to **2 seconds**). Events still in the queue after that window may not be delivered; command completion is never blocked longer than that timeout.

`pack --dry-run` lists files that would be packed but does **not** emit `cli_deploy_completed` or `cli_deploy_failed`.

## Super properties

Sent on every captured event:

| Property | Description |
|----------|-------------|
| `product` | `python_sdk` |
| `surface` | `terminal` |
| `environment` | `production`, `staging`, or `development` (from `NITROSTACK_ENVIRONMENT` or heuristics) |
| `app_version` | Installed `nitrostack` package version |
| `python_version` | Interpreter version |
| `sdk_version` | Same as `app_version` |
| `os_platform` | `sys.platform` |
| `os_arch` | `platform.machine()` |

## Events

| Event | When | Properties |
|-------|------|------------|
| `cli_command_invoked` | Every subcommand after parse | `command`: subcommand name (`init`, `pack`, …) |
| `cli_init_completed` | `init` finishes successfully | `template`, `skip_install`, `duration_ms`, `has_custom_description` |
| `cli_login_completed` | After `nitrostack-py login` succeeds (identity helper) | `user_email`, `cloud_user_id` (+ super properties) |
| `cli_deploy_completed` | `pack` writes a valid wheel | none beyond super properties |
| `cli_deploy_failed` | `pack` raises before success | `error_code`: exception type name (truncated) |

## Identity

- **Anonymous:** distinct id = first 16 hex chars of SHA-256(`hostname`:`username`), same scheme as the TypeScript CLI.
- **Login:** `login` runs `alias(anonymous, user_id)`, `identify(user_id, { email })`, optional `group_identify('organization', org_id)`, then `cli_login_completed`. Subsequent events use the Cloud user id as distinct id.

## Code locations

- Module: `nitrostack/cli/telemetry.py`
- CLI wiring: `nitrostack/cli/main.py` (`track_command_invoked`, `init`, `login`, `shutdown_telemetry`)
- Deploy: `nitrostack/cli/pack.py` (`cli_deploy_*`)
201 changes: 133 additions & 68 deletions nitrostack/cli/main.py
Original file line number Diff line number Diff line change
@@ -1,16 +1,24 @@
import argparse
import os
import re
import sys
import argparse
import shutil
import subprocess
import sys
import time
from pathlib import Path

from nitrostack.cli.generate import generate_component, generate_module as generate_module_from_template
from nitrostack.cli.generate import generate_component
from nitrostack.cli.generate import generate_module as generate_module_from_template
from nitrostack.cli.install import install_dependencies, lock_with_uv, rewrite_pyproject_identity
from nitrostack.cli.pack import pack_project
from nitrostack.cli.skills import run_skills_flow
from nitrostack.cli.telemetry import (
identify_from_cloud_login,
maybe_print_first_run_notice,
shutdown_telemetry,
track_command_invoked,
track_init_completed,
)
from nitrostack.cli.upgrade import upgrade_project
from nitrostack.cli.validators import format_report, validate_project

Expand Down Expand Up @@ -1267,6 +1275,7 @@ def _add_port_flags(parser):

def init_project(name: str = None, template: str = None, skip_install: bool = False, port=None, widget=None, force: bool = False):
print_banner()
init_started = time.monotonic()

# 1. Project name — optional CLI arg, otherwise the next readline
if not name:
Expand Down Expand Up @@ -1437,6 +1446,13 @@ def init_project(name: str = None, template: str = None, skip_install: bool = Fa
else:
print(" Try search_tools with 'overdue invoices', then invoke it through call_tool")
print("\nHappy coding! 🚀\n")
duration_ms = int((time.monotonic() - init_started) * 1000)
track_init_completed(
template=template,
skip_install=skip_install,
duration_ms=duration_ms,
has_custom_description=description.strip() != "My awesome MCP server",
)
return
if template == "python-oauth":
print(" 2. Configure OAuth credentials in your \033[34m.env\033[0m file")
Expand All @@ -1453,6 +1469,22 @@ def init_project(name: str = None, template: str = None, skip_install: bool = Fa
print(" 6. NitroStudio cannot folder-connect a Python project (it looks for @nitrostack/core).")
print(" Use Inspector HTTP as above, or Studio's custom MCP URL if it offers Streamable HTTP.")
print("\nHappy coding! 🚀\n")
duration_ms = int((time.monotonic() - init_started) * 1000)
track_init_completed(
template=template,
skip_install=skip_install,
duration_ms=duration_ms,
has_custom_description=description.strip() != "My awesome MCP server",
)

def run_login(user_id: str, email: str, org_id: str | None = None):
"""Associate the anonymous CLI distinct id with a NitroCloud user (analytics)."""
identify_from_cloud_login(
user_id=(user_id or "").strip(),
email=(email or "").strip(),
organization_id=(org_id or "").strip() or None,
)


def run_dev(port=None, widget=None):
target = "main.py"
Expand Down Expand Up @@ -1513,9 +1545,9 @@ def cleanup():

try:
start_process()

watched_extensions = {".py", ".env"}

def get_mtimes():
mtimes = {}
for root, dirs, files in os.walk("."):
Expand All @@ -1535,7 +1567,7 @@ def get_mtimes():
try:
from watchfiles import watch
print("Using watchfiles for high-performance file monitoring.")

while True:
for changes in watch("."):
should_restart = False
Expand All @@ -1549,11 +1581,11 @@ def get_mtimes():
if should_restart:
print("File changes detected! Restarting server...")
start_process()

time.sleep(0.5)
if process and process.poll() is not None:
print("Server process exited. Waiting for file changes to restart...")

except ImportError:
print("watchfiles library not found. Falling back to standard polling...")
last_mtimes = get_mtimes()
Expand Down Expand Up @@ -1673,7 +1705,7 @@ def generate_module(name: str):
def get_claude_config_paths():
paths = []
home = os.path.expanduser("~")

# Windows
if sys.platform == "win32":
appdata = os.environ.get("APPDATA")
Expand All @@ -1696,24 +1728,24 @@ def get_claude_config_paths():
# Linux
else:
paths.append(os.path.join(home, ".config", "Claude", "claude_desktop_config.json"))

return [p for p in paths if os.path.exists(os.path.dirname(p))]

def register_server(name: str, file_path: str):
import json

if not os.path.exists(file_path):
print(f"Error: Script file '{file_path}' does not exist.")
sys.exit(1)

server_entry = _build_server_entry(file_path)

config_paths = get_claude_config_paths()
if not config_paths:
print("Error: Could not find any Claude Desktop installation directories.")
print("Please ensure Claude Desktop is installed on your machine.")
sys.exit(1)

registered_any = False
for path in config_paths:
try:
Expand All @@ -1726,22 +1758,22 @@ def register_server(name: str, file_path: str):
config = json.loads(content)
except json.JSONDecodeError:
print(f"Warning: Configuration file at '{path}' is not valid JSON. Resetting it.")

if "mcpServers" not in config:
config["mcpServers"] = {}

config["mcpServers"][name] = server_entry

# Create directory if needed
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "w", encoding="utf-8") as f:
json.dump(config, f, indent=2)

print(f"Successfully registered server '{name}' in: {path}")
registered_any = True
except Exception as e:
print(f"Error writing to config at '{path}': {e}")

if registered_any:
print("\nAll done! Please fully restart Claude Desktop to load your new server.")
else:
Expand Down Expand Up @@ -1958,62 +1990,95 @@ def main():
help="Lint project config, @mcp_app imports, and @module() class references",
)

login_parser = subparsers.add_parser(
"login",
help=(
"Record NitroCloud user identity for analytics "
"(alias anonymous id to Cloud user id)"
),
)
login_parser.add_argument(
"--user-id",
required=True,
dest="user_id",
help="Stable NitroCloud user id",
)
login_parser.add_argument(
"--email",
required=True,
help="User email (e.g. user@example.com)",
)
login_parser.add_argument(
"--org-id",
default=None,
dest="org_id",
help="Organization id for group analytics (optional)",
)

args = parser.parse_args()

if not args.command:
parser.print_help()
sys.exit(1)

def _run_command(fn, *fn_args, **fn_kwargs):
try:
return fn(*fn_args, **fn_kwargs)
except Exception as exc:
print(f"Error: {exc}")
sys.exit(1)
try:
maybe_print_first_run_notice()
track_command_invoked(args.command)

if args.command == "init":
init_project(
args.name,
args.template,
skip_install=args.skip_install,
port=args.port,
widget=args.widget,
force=args.force,
)
elif args.command == "dev":
run_dev(port=args.port, widget=args.widget)
elif args.command == "start":
run_start(port=args.port, widget=args.widget)
elif args.command == "register":
register_server(args.name, args.file)
elif args.command == "cursor":
register_cursor_server(args.name, args.file, global_config=args.global_config, transport=args.transport)
elif args.command == "generate":
if not args.generator:
gen_parser.print_help()
sys.exit(1)
if args.generator == "tool":
generate_tool(args.name)
elif args.generator == "module":
generate_module(args.name)
else:
generate_component(args.generator, args.name)
elif args.command == "pack":
_run_command(pack_project, dry_run=args.dry_run)
elif args.command == "upgrade":
_run_command(
upgrade_project,
version=args.target_version,
dry_run=args.dry_run,
allow_downgrade=args.allow_downgrade,
)
elif args.command == "install":
_run_command(install_dependencies, production=args.production)
elif args.command == "validate":
issues = _run_command(validate_project)
print(format_report(issues))
if any(issue.severity == "error" for issue in issues):
sys.exit(1)
def _run_command(fn, *fn_args, **fn_kwargs):
try:
return fn(*fn_args, **fn_kwargs)
except Exception as exc:
print(f"Error: {exc}")
sys.exit(1)

if args.command == "init":
init_project(
args.name,
args.template,
skip_install=args.skip_install,
port=args.port,
widget=args.widget,
force=args.force,
)
elif args.command == "dev":
run_dev(port=args.port, widget=args.widget)
elif args.command == "start":
run_start(port=args.port, widget=args.widget)
elif args.command == "register":
register_server(args.name, args.file)
elif args.command == "cursor":
register_cursor_server(args.name, args.file, global_config=args.global_config, transport=args.transport)
elif args.command == "generate":
if not args.generator:
gen_parser.print_help()
sys.exit(1)
if args.generator == "tool":
generate_tool(args.name)
elif args.generator == "module":
generate_module(args.name)
else:
generate_component(args.generator, args.name)
elif args.command == "pack":
_run_command(pack_project, dry_run=args.dry_run)
elif args.command == "upgrade":
_run_command(
upgrade_project,
version=args.target_version,
dry_run=args.dry_run,
allow_downgrade=args.allow_downgrade,
)
elif args.command == "install":
_run_command(install_dependencies, production=args.production)
elif args.command == "validate":
issues = _run_command(validate_project)
print(format_report(issues))
if any(issue.severity == "error" for issue in issues):
sys.exit(1)
elif args.command == "login":
_run_command(run_login, args.user_id, args.email, args.org_id)
finally:
shutdown_telemetry()

if __name__ == "__main__":
main()
Loading
Loading