# Quable CLI

## Overview

The **Quable CLI** is a command-line tool available to everyone that lets you interact with the Quable ecosystem.  

This page covers:
- How to install the CLI  
- Core, general-purpose commands  
- Local configuration and usage tips

> **Note:** Partner-specific commands like `quable app create` and `quable app dev` (used to build apps for the Partner Portal) are documented in a separate Partner Portal guide. This page focuses on the general CLI usage available to all users.

---

## Installation

    npm install -g @quable/quable-cli

This installs the `quable` command globally.  
Make sure your Node.js version is compatible and that you have a package manager installed (npm, yarn, or pnpm).

---

## Authentication & Setup

Before using the CLI, log in to your Quable account:

    quable login

This starts an authentication flow (browser-based or token-based depending on your environment).  
The CLI stores session details in a local configuration (for example `.quablerc` or a folder `.quable/` in your project/home directory).

Reset / logout:

    quable logout

---

## Core Commands

| Command | Description | Options |
|---------|-------------|---------|
| `quable help` | Display help and available commands | — |
| `quable version` | Show the CLI version | — |
| `quable login` | Starts an authentication flow | `--instance`, `--user`, `--password`, `--token` |
| `quable logout` | Remove local credentials | — |
| `quable tunnel start` | Start an HTTP/HTTPS tunnel to expose a local server | `--port`, `--provider` |
| `quable tunnel stop` | Stop the current tunnel | — |
| `quable logs` | Show logs for a link or tunnel | `--follow`, `--since` |
| `quable whoami` | Show the currently logged-in user + instance | — |

> Commands and options may vary by CLI version. Refer to `quable help` for the most up-to-date list.

---

## Local Configuration

The CLI may use a local config file (`.quablerc`) to persist preferences:

- PIM Auth tokens
- PIM Instance

Example `.quablerc` (illustrative only — do not commit secrets):

    {
        "token": "xxxxxx",
        "instance": "myInstance"
    }

Store tokens securely and avoid committing credentials to version control.

---

## HTTP Tunnel

A common feature of the CLI is the ability to **open a secure public URL that tunnels to your local development server**. This is useful for testing webhooks, OAuth callbacks, and integrations that need a public endpoint.

Example:

    quable tunnel start --port 4000 --provider ngrok|localtunnel|localhost.run|cloudflare

The CLI will open a tunnel and return a public URL mapping to your local environment. To stop it:

    quable tunnel stop

Be aware of provider limits (session duration, concurrent tunnels, bandwidth) and pick a provider that fits your needs.

---

## Best Practices

- Keep the CLI up to date (reinstall via npm).  
- Never commit authentication tokens or secrets to public repositories.  
- Use environment-specific configs (local vs CI) and avoid storing long-lived secrets in local files if possible.  
- If behind a corporate firewall, verify required outbound ports and proxies are configured.

---

## Example Workflow

1. Install the CLI.  
2. Log in: `quable login`.  
3. Start a tunnel: `quable tunnel start --port 4000`.  
4. Develop and test webhooks / Slots' callbacks using the public URL returned by the CLI.  
5. Stop the tunnel: `quable tunnel stop`.

---

## Troubleshooting & Support

- Run `quable help` to see available commands and options.  
- Use `quable logs --follow` to tail logs for tunnels or linked sessions.  
- Check your network / firewall if tunnels fail to establish.  
- Contact Quable Support or your partner success manager for account-specific issues.

---

## Related Guides

- Partner Portal CLI (partner-only commands: `quable app create`, `quable app dev`) — see the Partner Portal guide.  
- CLI Release Notes — check the changelog for breaking changes and new features.

---