Skip to content

feat(website): improve Getting Started and CLI pages for better onboarding #1218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
betegon merged 2 commits into from
Dec 23, 2025
Merged

feat(website): improve Getting Started and CLI pages for better onboarding #1218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
178c782
improve onboarding docs
betegon Dec 23, 2025
f9c5a0b
new features and installation options
betegon Dec 23, 2025
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
4 changes: 4 additions & 0 deletions packages/website/astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,10 @@ export default defineConfig({
label: "What is Spotlight?",
link: "/docs/about/",
},
{
label: "Getting Started",
link: "/docs/setup/",
},
{
label: "Architecture",
link: "/docs/architecture/",
Expand Down
79 changes: 68 additions & 11 deletions packages/website/src/content/docs/docs/cli/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,27 +5,84 @@ sidebar:
order: 0
---

import { LinkCard, CardGrid } from '@astrojs/starlight/components';
import { Tabs, TabItem, LinkCard, CardGrid } from '@astrojs/starlight/components';

The Spotlight CLI (`spotlight`) provides two modes for working with Spotlight in your terminal:
The Spotlight CLI (`spotlight`) integrates Spotlight into your terminal workflow. Wrap your app to automatically capture telemetry, or stream events directly to your terminal.

## Two Modes of Operation
## Why Use the CLI?

- **Automatic instrumentation**: `spotlight run` sets up environment variables and captures output automatically
- **Real-time streaming**: View errors, logs, and traces directly in your terminal
- **Multiple output formats**: Human-readable, JSON, logfmt, or Markdown
- **Docker Compose support**: Auto-injects configuration into containerized services
- **Scriptable**: Perfect for CI/CD pipelines and automation

## Installation

<Tabs>
<TabItem label="npx">
No installation needed:
```bash
npx @spotlightjs/spotlight run npm run dev
Copy link
Member

@BYK BYK Dec 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
npx @spotlightjs/spotlight run npm run dev
npx @spotlightjs/spotlight run

Copy link
Member Author

@betegon betegon Dec 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good point.

```
</TabItem>
<TabItem label="npm global">
```bash
npm install -g @spotlightjs/spotlight
```
</TabItem>
<TabItem label="Binary">
```bash
curl -q https://spotlightjs.com/install.sh | sh
```
</TabItem>
<TabItem label="Docker">
```bash
docker run -p 8969:8969 ghcr.io/getsentry/spotlight:latest
```
</TabItem>
</Tabs>

## Commands

<CardGrid>
<LinkCard
title="Tail Command"
title="spotlight run"
href="/docs/cli/run/"
description="Wrap your app to automatically capture telemetry and stream events."
/>
<LinkCard
title="spotlight tail"
href="/docs/cli/tail/"
description="Stream and filter Spotlight events in real-time from your terminal"
description="Stream and filter events in real-time. Connect to an existing sidecar or start a new one."
/>
<LinkCard
title="Run Command"
href="/docs/cli/run/"
description="Wrap your application to automatically capture telemetry. Also streams events in real-time like the tail command."
title="spotlight server"
href="/docs/cli/reference/#server---start-standalone-server"
description="Start the sidecar server with web UI at localhost:8969."
/>
<LinkCard
title="spotlight mcp"
href="/docs/mcp/"
description="Start MCP server for AI coding assistants like Cursor and Claude."
/>

</CardGrid>

## Quick Reference
## CLI vs Desktop App

| | CLI | Desktop App |
|---|---|---|
| **Best for** | Terminal workflows, automation | Visual debugging, dedicated window |
| **Platform** | All (via Node.js or binary) | macOS (Win/Linux coming soon) |
| **Output** | Terminal + browser UI | Built-in UI |
| **Features** | Wrap apps, stream to files, CI/CD | Auto-updates, native experience |

[Learn more about Desktop App →](/docs/desktop-app/)

- [Complete CLI Reference](/docs/cli/reference/) - All commands and options
## Reference

<LinkCard
title="Complete CLI Reference"
href="/docs/cli/reference/"
description="All commands, options, and environment variables"
/>
98 changes: 50 additions & 48 deletions packages/website/src/content/docs/docs/setup/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,52 +1,54 @@
---
title: Using Spotlight
description: Use Spotlight as a standalone application
title: Getting Started
description: Choose how to run Spotlight in your development environment
sidebar:
order: 0
---
import DownloadButton from '../../../../components/DownloadButton.astro';
import { Tabs, TabItem } from '@astrojs/starlight/components';

Spotlight provides an Electron app that can be used to run the Sidecar as well as a dedicated instance of the overlay.

## Installation

Get started by downloading the latest version of the Electron app for your platform.

<DownloadButton>Download for Mac</DownloadButton>

### Other ways

If Electron apps are not your thing or you are not using a Mac we have some more ways to run Spotlight with it's web UI:

<Tabs>
<TabItem label="npx">
```shell
npx @spotlightjs/spotlight
```
</TabItem>
<TabItem label="docker">
```shell
docker run --rm -p 8969 ghcr.io/getsentry/spotlight:latest
```
</TabItem>
<TabItem label="binary">
```shell
curl -q https://spotlightjs.com/install.sh | sh
```
</TabItem>
</Tabs>

## SDK Setup

In addition to loading the application, make sure you've enabled spotlight in the relevant Sentry SDKs (e.g. via `spotlight: true`):

For front-end applications, you need to enable the `browserTracingIntegration` for tracing to work. This is to only include this bit of the code for the users of Spotlight:

```javascript
import * as Sentry from '@sentry/browser';
import { Tabs, TabItem, LinkCard, CardGrid } from '@astrojs/starlight/components';
import DownloadButton from '../../../../components/DownloadButton.astro';

Sentry.init({
dsn: '___DSN___',
integrations: [Sentry.browserTracingIntegration()],
// ...other Sentry options
});
```
Spotlight offers several ways to run depending on your workflow and preferences. All options provide the same core debugging capabilities. Choose the one that fits best.

## Three Ways to Run Spotlight
:::tip[Combine Options]
You can use multiple options together. For example, run the Desktop App for visual debugging while also connecting Cursor via MCP for AI-assisted debugging.
:::
| Option | Best For | Platform | UI |
|--------|----------|----------|-----|
| **Desktop App** | Visual debugging in a dedicated window | All platforms | Built-in |
| **CLI** | Terminal workflows, wrapping apps, automation | All platforms | Browser |
| **MCP Server** | AI-assisted debugging with Cursor, Claude, etc. | All platforms | none |

<CardGrid>
<LinkCard
title="Desktop App"
href="/docs/desktop-app/"
description="Standalone app with built-in UI. Best for visual debugging and dedicated window workflows."
/>
<LinkCard
title="CLI"
href="/docs/cli/"
description="Run apps with automatic instrumentation, stream events to your terminal, or start the sidecar server."
/>
<LinkCard
title="MCP Server"
href="/docs/mcp/"
description="Connect Spotlight to AI coding assistants like Cursor and Claude for AI-assisted debugging."
/>
</CardGrid>




## Next Steps

After choosing your setup method, you may need to configure your application's Sentry SDK:

<LinkCard
title="SDK Configuration"
href="/docs/sidecar/#sdk-integration"
description="Learn how to configure Sentry SDKs to send data to Spotlight"
/>

Most SDKs automatically detect the `SENTRY_SPOTLIGHT` environment variable—just set it to `1` or the sidecar URL.
Loading