Getting Started with Periscope

Install the CLI, log in, and create your first secure tunnel in under two minutes.

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 by checking the version:

periscope --version

You should see the current version number printed to the console.

2 Log In

Authenticate with the Periscope server. This opens your browser where you can sign up or sign in with your email:

periscope auth login

After signing in, verify your authentication status:

periscope auth status

You should see your email address and account status confirmed.

3 Create Your First Tunnel

Create a tunnel that exposes your local development server to a public URL:

periscope tunnel connect my-app --localPort 3000

This creates a tunnel named my-app that forwards traffic from the Periscope server to port 3000 on your machine.

Options

Use a custom port with the -p flag:

periscope tunnel connect my-app -p 8080

Set a custom host header with --localHost:

periscope tunnel connect my-app --localPort 3000 --localHost myapp.local

4 Check Server Status

Check the status of the Periscope server and your active tunnels:

periscope status

This displays connection health, server version, and a list of your active tunnels.

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 guided experience. The interactive CLI walks you through tunnel creation and configuration with prompts:

periscope --interactive

Interactive mode is ideal when you are getting started or want to explore available options without memorizing commands.

Configuration

View your current configuration with:

periscope config show

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

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

Configuration Priority

Periscope resolves configuration values in the following order (highest priority first):

  1. Environment variables — override everything
  2. .env file — project-level defaults
  3. Config file — persisted via periscope config set

Common Use Cases

webhook

Webhook Development

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

periscope tunnel connect webhooks --localPort 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 tunnel connect mobile-api --localPort 8080
share

Sharing Work in Progress

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

periscope tunnel connect demo --localPort 5173
dns

Multi-Service Development

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

periscope tunnel connect frontend --localPort 3000
periscope tunnel connect api --localPort 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 --localPort 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

Periscope is in beta and we are actively improving it 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]