TunnelHub CLI

TunnelHub CLI is a command-line interface tool that helps developers interact with TunnelHub services directly from their terminal. It simplifies managing environments, packages, and automations for creating and deploying integrations in the TunnelHub ecosystem.

Features

• Secure authentication with TunnelHub accounts
• Environment management and listing
• Package creation and listing
• Automation creation, listing, and deployment
• Support for different runtime engines (Lambda and ECS Fargate)
• Intuitive command-line interface with guided prompts

Installation

To use the TunnelHub CLI, you need Node.js installed on your system. Download it from nodejs.org if you don't have it yet.

Install the TunnelHub CLI globally using npm:

npm install -g @tunnelhub/cli

Or using yarn:

yarn global add @tunnelhub/cli

After installation, you can access the CLI using either tunnelhub or the shorthand th command.

Release

This package is published automatically by GitHub Actions when a version tag in the format v* is pushed.

# Create a new patch, minor, or major version
npm run release:patch

# Push the release commit and tag
git push && git push --tags

Available helper scripts:

npm run release:patch
npm run release:minor
npm run release:major

Usage

Authentication

The CLI discovers the public Cognito configuration from the selected server before login. Users only run:

tunnelhub login

This opens Cognito Managed Login with Authorization Code + PKCE (S256). No environment variables or client secret are needed for human login. Production is the default; tunnelhub login --env selects QAS or DEV.

Login no longer asks for a tenant ID. Authenticate with your shared account first; the CLI selects the only accessible tenant automatically or asks you to choose when several are available.

Switch tenant while remaining logged in:

tunnelhub tenant list
tunnelhub tenant list --json
tunnelhub tenant use
tunnelhub tenant use <tenant-id>
tunnelhub tenant current

The default tenant list is displayed as a table. Use --json when another command or script needs the backend response format.

Switching tenants clears the selected environment. Access is always checked by the backend, including global SystemAdmin/SystemSupport access. A tenant that requires SAML needs authentication through its provider.

Existing sessions must log in again after the migration. Migrated local accounts may need a password reset; use browser login for password reset, MFA and SAML. The browser redirects directly to the local CLI callback.

Browser login opens Cognito Managed Login. Password login also discovers the shared public client:

tunnelhub login --password

To verify your authentication status:

tunnelhub login-check

To log out and remove your credentials:

tunnelhub logout

See authentication contracts and integration dependencies for callback requirements, refresh behavior, migration and API details.

Managing Environments

List your available environments:

tunnelhub list-environments
tunnelhub use-environment <environment-id-or-name>

Package and automation list/create commands use this selected environment when --env is omitted. Explicit --env takes precedence. Deploy commands continue requiring an explicit environment.

Working with Packages

List your existing packages:

tunnelhub list-packages

Create a new package:

tunnelhub create-package

Working with Automations

List your automations:

tunnelhub list-automations

Create a new automation:

tunnelhub create-automation --env [environment-id]

When creating automations, you can choose from four base designs:

• No delta (individual)
• No delta (batch)
• Delta (individual)
• Delta (batch)

Deploy an automation:

tunnelhub deploy-automation --env [environment-id] --automation [automation-id] --message "Deploy message"

CI/CD Deployments

The CLI also supports machine-to-machine deploys without tunnelhub login.

Required environment variables:

• TH_API_HOST
• TH_CLIENT_ID
• TH_CLIENT_SECRET

Recommended variables for the pipeline script:

• TH_ENVIRONMENT_ID
• TH_AUTOMATION_ID

In CI/CD mode, the deploy revision keeps the API client identity in createdBy and the human context should be sent in --message.

Example with GitHub Actions:

COMMIT_EMAIL="$(git log -1 --pretty=format:'%ae')"
COMMIT_SHA="$(git rev-parse --short HEAD)"

th deploy-automation \
  --environment-id "$TH_ENVIRONMENT_ID" \
  --automation "$TH_AUTOMATION_ID" \
  --message "GitHub Actions deploy ${COMMIT_SHA} by ${COMMIT_EMAIL}"

Help and Version

Display the help menu:

tunnelhub --help

Check the CLI version:

tunnelhub --version

Common Workflows

Creating and Deploying an Automation

1. Log in to your TunnelHub account:

   tunnelhub login

2. List your environments and note the environment ID where you want to create the automation:

   tunnelhub list-environments

3. Create a new automation:

   tunnelhub create-automation --env [environment-id]

4. Follow the interactive prompts to configure your automation settings, including the automation type, runtime engine, and other parameters.

5. Deploy your automation:

   tunnelhub deploy-automation --env [environment-id] --automation [automation-id] --message "Deploy message"

Authentication discovery for maintainers

Before generic login, the CLI calls GET /tenant-service/auth/public-config without authentication or tenant headers. It validates schemaVersion: 1, issuer, discoveryUrl, domain, clientId and scopes, then uses the OIDC discovery document's authorization/token endpoints. No Cognito IDs or domains are bundled, and no human authentication environment variables are required. An unavailable or invalid endpoint stops login with an error; it does not fall back to a different environment or stale configuration.

For a known tenant, especially SAML, use tunnelhub login --tenant <tenant-id> (add --env to select QAS/DEV). This reads /tenant-service/tenants/public/{id} and uses that tenant's human client, pool and provider. It does not replace SAML routing with the generic client. After login, the backend still validates accessible tenants. tenant use <id> switches working context without logging in again unless the backend requires SAML authentication.

The public human app client (including each SAML client used by the CLI) must allow Authorization Code + PKCE, openid email profile as applicable, Managed Login v2/branding, and the exact callback http://localhost:3333/auth/callback. The generic login uses the scopes from public config; the existing tenant response does not expose scopes, so tenant login retains openid email profile. These are backend deployment prerequisites; the CLI does not alter infrastructure. CI still uses TH_CLIENT_ID and TH_CLIENT_SECRET separately.

Support

If you encounter any issues or have questions about using TunnelHub CLI, please visit our GitHub repository or contact support at the email provided in the package information.

License

TunnelHub CLI is licensed under the ISC License.