Skip to main content
The Decipher Tunnel CLI exposes your local development server to the internet through a secure tunnel, giving Decipher’s test runner a public URL to reach your app. This lets you record and run tests against localhost without deploying — powered by ngrok under the hood.
Prerequisites:
  • Node.js 18 or later
  • A Decipher account
  • A local dev server running on a known port (e.g., localhost:3000)

​
Step 1: Install the CLI

Install the tunnel CLI globally using your preferred package manager: 
npm install -g @decipher-sdk/decipher-tunnel

​
Step 2: Authenticate

1

Start the login flow

Run the login command in your terminal:
decipher-tunnel login
Your browser will open to the Decipher dashboard.
2

Copy your token

The dashboard displays a one-time authentication token. Click the copy button to copy it to your clipboard.
3

Paste the token

Switch back to your terminal and paste the token when prompted. You’ll see a success message confirming you’re logged in.

​
Step 3: Start a Tunnel

1

Start your local dev server

Make sure your app is running locally. For example:
npm run dev
Confirm it’s accessible at http://localhost:3000 (or whichever port you use).
2

Open the tunnel

In a separate terminal window, run:
decipher-tunnel forward -p 3000
Replace 3000 with your local server’s port. The CLI will start the tunnel and display your public URL:
https://{userId}.tunnel.getdecipher.com
Incoming requests are logged in real-time so you can see test traffic as it arrives.
3

Stop the tunnel

Press Ctrl+C in the terminal to stop the tunnel, or run:
decipher-tunnel kill

​
Step 4: Use the Tunnel URL in Decipher

Once your tunnel is running, use the public URL as the Base URL when recording or running tests in the Decipher dashboard. Any test pointed at that URL will hit your local server through the tunnel.
Your tunnel URL is stable — it stays the same every time you run decipher-tunnel forward, so you don’t need to update your tests each session.

​
CLI Reference

CommandDescription
decipher-tunnel loginAuthenticate with Decipher
decipher-tunnel logoutRevoke stored credentials
decipher-tunnel forward -p <port>Start a tunnel to the given local port
decipher-tunnel meShow the currently authenticated user
decipher-tunnel listShow the active tunnel
decipher-tunnel killStop the active tunnel

​
Troubleshooting

Only one tunnel can be active at a time. Stop the existing tunnel first:
decipher-tunnel kill
Then start a new one with decipher-tunnel forward -p <port>.
Your session may have expired. Log in again:
decipher-tunnel login
If the issue persists, log out first and then log back in:
decipher-tunnel logout
decipher-tunnel login
This usually means your local dev server isn’t running. Make sure your app is started and accessible at the port you forwarded before sending traffic through the tunnel.
Need help? Contact our support team.