# Tableau CLI

The Paradime SDK provides CLI commands to interact with Tableau, allowing you to refresh workbooks and data sources, and list available resources.

{% hint style="warning" %}
🔑 **API Access Required**

You will need a Tableau Personal Access Token to use these commands. You can create one in your Tableau Server account settings: [Personal Access Tokens](https://help.tableau.com/current/server/en-us/security_personal_access_tokens.htm)

#### 🔧 Configure Data Source Credentials

To enable Paradime to trigger a data extract refresh, ensure that any required credentials are embedded within the extract:

1. Edit the data source in Tableau
2. Click **'Publish'**
3. Select **'Embed credentials'**
   {% endhint %}

## Refresh Tableau Resources

Trigger refreshes for Tableau workbooks or data sources with monitoring capabilities.

### CLI Command

```bash
paradime run tableau-refresh
```

#### Options

<table><thead><tr><th width="322.60546875">Flag</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>--site-name</code></td><td>Optional, TEXT</td><td>The name of the Tableau site. Only set this if using a site other than the default site. Can be set via <code>TABLEAU_SITE_NAME</code> environment variable.</td></tr><tr><td><code>--workbook-name</code></td><td>Optional, TEXT (multiple)</td><td>The name or UUID of the workbook(s) you want to refresh. Can specify multiple workbooks.</td></tr><tr><td><code>--datasource-name</code></td><td>Optional, TEXT (multiple)</td><td>The name or UUID of the data source(s) you want to refresh. Can specify multiple data sources.</td></tr><tr><td><code>--host</code></td><td>Required, TEXT</td><td>The base URL of your Tableau server (e.g., <code>https://prod-uk-a.online.tableau.com/</code>). Can be set via <code>TABLEAU_HOST</code> environment variable.</td></tr><tr><td><code>--personal-access-token-secret</code></td><td>Required, TEXT</td><td>Your Tableau personal access token secret. Can be set via <code>TABLEAU_PERSONAL_ACCESS_TOKEN_SECRET</code> environment variable.</td></tr><tr><td><code>--personal-access-token-name</code></td><td>Required, TEXT</td><td>Your Tableau personal access token name. Can be set via <code>TABLEAU_PERSONAL_ACCESS_TOKEN_NAME</code> environment variable.</td></tr><tr><td><code>--wait-for-completion</code> / <code>--no-wait-for-completion</code></td><td>Optional, Flag</td><td>Wait for the refresh job to complete before returning. Shows progress and final status. Default: <code>--wait-for-completion</code>.</td></tr><tr><td><code>--timeout-minutes</code></td><td>Optional, INTEGER</td><td>Maximum time to wait for refresh completion (in minutes). Only used with <code>--wait-for-completion</code>. Default: 30. Can be set via <code>TABLEAU_REFRESH_TIMEOUT_MINUTES</code> environment variable.</td></tr></tbody></table>

{% hint style="info" %}
**Recommended Setup**

For security and convenience, set your Tableau credentials as environment variables:

```bash
TABLEAU_HOST="https://prod-uk-a.online.tableau.com/"
TABLEAU_PERSONAL_ACCESS_TOKEN_NAME="mytoken"
TABLEAU_PERSONAL_ACCESS_TOKEN_SECRET="mysecret"
TABLEAU_SITE_NAME="mys-site"  # Optional, only if using non-default site
```

{% endhint %}

## **Workbook Refresh Examples**

### **Refresh a single workbook by name**

```bash
# Using environment variables (recommended)
paradime run tableau-refresh --workbook-name "Sales Dashboard"

# Or with explicit flags
paradime run tableau-refresh \
  --host "https://prod-uk-a.online.tableau.com/" \
  --personal-access-token-name "mytoken" \
  --personal-access-token-secret "mysecret" \
  --workbook-name "Sales Dashboard"
```

### **Refresh a workbook by UUID**

```bash
# Using environment variables (recommended)
paradime run tableau-refresh --workbook-name "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

# Or with explicit flags
paradime run tableau-refresh \
  --host "https://tableau.company.com/" \
  --personal-access-token-name "mytoken" \
  --personal-access-token-secret "mysecret" \
  --workbook-name "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
```

## **Data Source Refresh Examples**

### **Refresh a single data source by name**

```bash
# Using environment variables (recommended)
paradime run tableau-refresh --datasource-name "Sales Data"

# Or with explicit flags
paradime run tableau-refresh \
  --host "https://tableau.company.com/" \
  --personal-access-token-name "mytoken" \
  --personal-access-token-secret "mysecret" \
  --datasource-name "Sales Data"
```

### **Refresh a data source by UUID**

```bash
# Using environment variables (recommended)
paradime run tableau-refresh --datasource-name "12345678-1234-1234-1234-123456789012"

# Or with explicit flags
paradime run tableau-refresh \
  --host "https://tableau.company.com/" \
  --personal-access-token-name "mytoken" \
  --personal-access-token-secret "mysecret" \
  --datasource-name "12345678-1234-1234-1234-123456789012"
```

{% hint style="success" %}

## Sample Output

```
Tableau workbook refresh started on site production...
2024-01-15 10:30:00 - Refreshing Tableau workbook: Sales Dashboard
2024-01-15 10:30:01 - Input appears to be an ID, trying direct access: 'Sales Dashboard'
2024-01-15 10:30:02 - Searching for workbook by name: 'Sales Dashboard'
2024-01-15 10:30:02 - Found workbook by name: 'Sales Dashboard' -> UUID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
2024-01-15 10:30:03 - Monitoring refresh job job-12345 for workbook 'Sales Dashboard'...
2024-01-15 10:30:03 - Job job-12345 progress: 0% (started at 2024-01-15T10:30:03Z)
2024-01-15 10:32:33 - Job job-12345 progress: 50% (started at 2024-01-15T10:30:03Z)
2024-01-15 10:34:45 - ✅ Workbook 'Sales Dashboard' refresh completed successfully in 4m 42s
2024-01-15 10:34:45 - Refreshed Tableau workbook: Sales Dashboard - Refresh completed. Job status: SUCCESS (finished at 2024-01-15T10:34:45Z)
```

{% endhint %}

## List Tableau Workbooks

List all available Tableau workbooks with their names, UUIDs, and project information.

### CLI Command

```bash
paradime run tableau-list-workbooks
```

#### Options

| Flag                             | Type           | Description                                                                                                                                       |
| -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--site-name`                    | Optional, TEXT | The name of the Tableau site. Only set this if using a site other than the default site. Can be set via `TABLEAU_SITE_NAME` environment variable. |
| `--host`                         | Required, TEXT | The base URL of your Tableau server (e.g., `https://prod-uk-a.online.tableau.com/`). Can be set via `TABLEAU_HOST` environment variable.          |
| `--personal-access-token-secret` | Required, TEXT | Your Tableau personal access token secret. Can be set via `TABLEAU_PERSONAL_ACCESS_TOKEN_SECRET` environment variable.                            |
| `--personal-access-token-name`   | Required, TEXT | Your Tableau personal access token name. Can be set via `TABLEAU_PERSONAL_ACCESS_TOKEN_NAME` environment variable.                                |

### Usage Example

```bash
# Using environment variables (recommended)
paradime run tableau-list-workbooks

# Or with explicit flags
paradime run tableau-list-workbooks \
  --host "https://prod-uk-a.online.tableau.com/" \
  --personal-access-token-name "mytoken" \
  --personal-access-token-secret "mysecret"
```

{% hint style="success" %}

#### Sample Output

```
Listing Tableau workbooks on site production...
2024-01-15 10:30:00 - Found 3 workbook(s):
2024-01-15 10:30:00 -   Sales Dashboard | a1b2c3d4-e5f6-7890-abcd-ef1234567890 | Project: Analytics
2024-01-15 10:30:00 -   Marketing Report | b2c3d4e5-f6g7-8901-bcde-f23456789012 | Project: Marketing
2024-01-15 10:30:00 -   Executive Summary | c3d4e5f6-g7h8-9012-cdef-345678901234 | Project: Executive
```

{% endhint %}

## List Tableau Data Sources

List all available Tableau data sources with their names, UUIDs, types, and project information.

### CLI Command

```bash
paradime run tableau-list-datasources
```

#### Options

| Flag                             | Type           | Description                                                                                                                                       |
| -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--site-name`                    | Optional, TEXT | The name of the Tableau site. Only set this if using a site other than the default site. Can be set via `TABLEAU_SITE_NAME` environment variable. |
| `--host`                         | Required, TEXT | The base URL of your Tableau server (e.g., `https://prod-uk-a.online.tableau.com/`). Can be set via `TABLEAU_HOST` environment variable.          |
| `--personal-access-token-secret` | Required, TEXT | Your Tableau personal access token secret. Can be set via `TABLEAU_PERSONAL_ACCESS_TOKEN_SECRET` environment variable.                            |
| `--personal-access-token-name`   | Required, TEXT | Your Tableau personal access token name. Can be set via `TABLEAU_PERSONAL_ACCESS_TOKEN_NAME` environment variable.                                |

### Usage Example

```bash
# Using environment variables (recommended)
paradime run tableau-list-datasources

# Or with explicit flags
paradime run tableau-list-datasources \
  --host "https://prod-uk-a.online.tableau.com/" \
  --personal-access-token-name "mytoken" \
  --personal-access-token-secret "mysecret"
```

{% hint style="success" %}

#### Sample Output

```
Listing Tableau data sources on site production...
2024-01-15 10:30:00 - Found 2 data source(s):
2024-01-15 10:30:00 -   Sales Data | d4e5f6g7-h8i9-0123-defg-456789012345 | Type: sqlserver | Project: Data Sources
2024-01-15 10:30:00 -   Customer Analytics | e5f6g7h8-i9j0-1234-efgh-567890123456 | Type: postgres | Project: Analytics
```

{% endhint %}

## Important Notes

* **Resource Identification**: Both workbook and data source names and UUIDs are supported interchangeably in refresh commands.
* **Site Management**: If you're using Tableau Server with multiple sites, specify the site name. For Tableau Online or default sites, you can omit this parameter.
* **Job Monitoring**: When `--wait-for-completion` is enabled, the CLI will monitor refresh job progress and provide detailed status updates.
* **Environment Variables**: All authentication parameters can be set as environment variables for security and convenience.

## Environment Variable Reference

| Environment Variable                   | Description                              |
| -------------------------------------- | ---------------------------------------- |
| `TABLEAU_HOST`                         | Base URL of your Tableau server          |
| `TABLEAU_PERSONAL_ACCESS_TOKEN_NAME`   | Personal access token name               |
| `TABLEAU_PERSONAL_ACCESS_TOKEN_SECRET` | Personal access token secret             |
| `TABLEAU_SITE_NAME`                    | Tableau site name (optional)             |
| `TABLEAU_REFRESH_TIMEOUT_MINUTES`      | Refresh timeout in minutes (default: 30) |

## Workflow Integration

These Tableau CLI commands are designed to integrate seamlessly into your data pipeline workflows. Common use cases include:

1. **Post-dbt Refresh**: Trigger Tableau refreshes after dbt model runs complete
2. **Scheduled Data Updates**: Automate regular refresh cycles for critical dashboards
3. **CI/CD Integration**: Include Tableau refreshes in your deployment pipelines
4. **Resource Discovery**: Use list commands to programmatically discover available workbooks and data sources

For more information about integrating Tableau refreshes into your Paradime workflows, see the [Bolt Schedules documentation.](https://docs.paradime.io/app-help/documentation/bolt)