Server Commands

Reference for the Pointa server CLI commands.

Overview

The Pointa server manages:

MCP protocol for AI tool communication
HTTP API for Chrome extension
Local storage for annotations and reports

Basic Commands

Start Server

npx pointa-server start

Starts the server in the background on port 4242.

Output:

Pointa server started on port 4242

Stop Server

npx pointa-server stop

Stops the running server.

Output:

Pointa server stopped

Check Status

npx pointa-server status

Shows current server status.

Output (running):

Pointa server is running on port 4242

Output (stopped):

Pointa server is not running

Restart Server

npx pointa-server restart

Stops and restarts the server. Useful after updates.

Log Commands

View Logs

npx pointa-server logs

Shows recent server logs.

Follow Logs

npx pointa-server logs -f

Continuously streams logs (like tail -f). Press Ctrl+C to stop.

Configuration

Custom Port

Change the server port using an environment variable:

POINTA_PORT=4243 npx pointa-server start

To make it permanent, add to your shell profile:

# In ~/.zshrc or ~/.bashrc
export POINTA_PORT=4243

Note: If you change the port, update:

Chrome extension settings
Your AI tool's MCP configuration

Data Locations

All Pointa data is stored in ~/.pointa/:

File	Purpose
`annotations.json`	Active annotations (pending and in-review)
`issue_reports.json`	Bug and performance reports
`archive.json`	Completed annotations and resolved issues
`inspirations.json`	Saved inspiration captures
`images/`	Uploaded annotation images
`bug_screenshots/`	Bug report screenshots
`inspiration_screenshots/`	Inspiration mode captures

Global Installation

For convenience, you can install globally:

npm install -g pointa-server

Then use without npx:

pointa-server start
pointa-server status
pointa-server stop

Running as Background Service

macOS (Launch Agent)

Create ~/Library/LaunchAgents/com.pointa.server.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.pointa.server</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/npx</string>
        <string>pointa-server</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Load it:

launchctl load ~/Library/LaunchAgents/com.pointa.server.plist

Linux (systemd)

Create /etc/systemd/user/pointa.service:

[Unit]
Description=Pointa Server
After=network.target

[Service]
ExecStart=/usr/bin/npx pointa-server start
Restart=always

[Install]
WantedBy=default.target

Enable:

systemctl --user enable pointa
systemctl --user start pointa

Troubleshooting

Port Already in Use

Check what's using the port:

lsof -i :4242

Kill the process or use a different port.

Server Won't Start

Check for existing instances
Try stopping first: npx pointa-server stop
Check logs for errors

Data Corruption

If annotations aren't loading:

Stop the server
Check ~/.pointa/annotations.json for valid JSON
Backup and fix or delete if needed
Restart server

API Endpoints

The server exposes these endpoints:

Endpoint	Purpose
`GET /health`	Health check
`GET /api/annotations`	List annotations
`POST /api/annotations`	Create annotation
`PUT /api/annotations/:id`	Update annotation
`DELETE /api/annotations/:id`	Delete annotation
`/mcp`	MCP protocol endpoint
`/sse`	Server-sent events