Getting Started with Periscope

Install the CLI and expose your local service to the internet in two commands.

Prerequisites

Before you begin, make sure you have the following installed on your machine:

  • check_circle Node.js 20+ — download from nodejs.org
  • check_circle npm — included with Node.js
  • check_circle A web browser — for authentication (any modern browser works)

1 Install the CLI

Install Periscope globally using npm:

npm install -g @elf5/periscope

Verify the installation:

periscope --version

2 Share Your First Service

Run the share command with a name for your tunnel. --target is optional — without it, Periscope tunnels to http://localhost:80:

periscope share my-app

Use --target to specify the service to tunnel:

periscope share my-app --target http://localhost:3000

Why set --target correctly? The target URL tells Periscope which host and port to forward requests to. Many frameworks also rely on this value to construct absolute URLs — for example, CSRF token validation, Location headers in redirects, OAuth callback URLs, and Referrer-Policy behaviour. Setting --target to match your running service ensures those features work correctly through the tunnel.

The CLI handles everything automatically on first run:

  1. Authentication — your browser opens so you can sign up or sign in
  2. SSH key setup — a key pair is generated and registered with the server
  3. Slug assigned — a random URL slug is generated for you (you can change it to something memorable later)
  4. Tunnel live — your local service is now accessible at a public HTTPS URL

Options

Tunnel to a service on a non-standard port:

periscope share my-app --target http://localhost:8080

Tunnel to a local HTTPS service or a non-localhost host (useful for virtual-host setups):

periscope share my-app --target https://myapp.local:8443

3 Set Your Slug (recommended)

A slug is automatically assigned when you first sign in. To change it to something memorable and easy to share:

periscope user slug myname

Every tunnel you create will then follow the format:

{name}-myname.periscope.elf5.com

4 Check Status

Verify your setup at any time:

periscope status

This shows server health and version, authentication status, SSH key details, and your personal tunnel URL format.

5 Live Request Logging

Live HTTP request logging is enabled by default. Every request that passes through your tunnel is logged to the console in real time, including method, path, status code, and timing.

To disable request logging:

periscope config set --request-log false

Re-enable it at any time by setting the value back to true.

6 Interactive Mode

Launch Periscope in interactive mode for a persistent session with tab completion. Session management and replay commands are available here:

periscope -i

Manage Sessions

See all your active sessions:

periscope > sessions

Close a specific session by name:

periscope > close my-app

Close all sessions at once:

periscope > close --all

Request Replay

Periscope captures HTTP requests flowing through your tunnels. You can replay them for debugging:

periscope > replay my-app

Other Commands

Authentication

Re-authenticate manually (useful if your session expires):

periscope auth login
periscope auth logout

Configuration

View your current configuration:

periscope config show

Change the server URL (useful if your organization self-hosts Periscope):

periscope config set --server https://periscope.yourcompany.com

Common Use Cases

webhook

Webhook Development

Receive webhooks from third-party services (Stripe, GitHub, Twilio) on your local machine without deploying.

periscope share webhooks --target http://localhost:3000
phone_iphone

Mobile App Development

Point your mobile app at the tunnel URL to test against a local API server running on your development machine.

periscope share mobile-api --target http://localhost:8080
share

Sharing Work in Progress

Share a live preview of your work with teammates or stakeholders without deploying to a staging environment.

periscope share demo --target http://localhost:5173
dns

Multi-Service Development

Expose multiple local services at the same time, each on its own tunnel with its own public URL.

periscope share frontend --target http://localhost:3000
periscope share api --target http://localhost:8080

Troubleshooting

  • error_outlineServer is unreachable

    Check your internet connection and verify the server URL is correct with periscope config show. If your organization self-hosts Periscope, confirm the server address with your admin. You can update it with:

    periscope config set --server https://periscope.yourcompany.com
  • error_outlineAuthentication Fails

    Try logging out and back in to refresh your credentials:

    periscope auth logout
periscope auth login

    Make sure your browser completes the sign-in flow and returns you to the CLI confirmation page. If the issue persists, check that your system clock is accurate.

  • error_outlineTunnel Won't Connect

    Verify that the local service is running on the port you specified. For example, if you used --target http://localhost:3000, confirm your app is listening on port 3000. Also check that no firewall rules are blocking local connections. Run periscope status to see detailed connection diagnostics.

We Want Your Feedback

We're actively improving Periscope based on your input. Tell us what is working, what is not, and what you would like to see next.

Logged-in users can send feedback directly from the CLI:

periscope feedback "Your message here"

Not logged in? Email us at [email protected]