Skip to main content

Open File

Available September 2026 and later.

Opens a local file in Tableau Studio by absolute path: a .twb/.twbx opens as a workbook, while a datasource file (Excel, .tds, extract, and the like) attaches to the open workbook. Opening a workbook while one is already open launches a new window, but this session stays bound to the original — reads keep reporting the first workbook, not the newly opened one.

Not read-only

This tool is not read-only and not idempotent. It opens a file in the live Tableau Studio session, so repeating the call is not a no-op.

APIs called​

This tool acts on the running Tableau Studio instance, not on the Tableau Cloud or Tableau Server REST API. Under the hood this is a call to the local Tableau Studio External Client API — a REST API the running Tableau Studio instance serves at http://127.0.0.1:<port>/v<x>, where <x> is the latest API version. There are no OAuth scopes: the call is authorized by the running Tableau Studio instance's per-session bearer token over the loopback interface.

  • Settles on which Tableau Studio session to target before anything is sent. Resolved in-process (not an API call).
  • Asks Tableau Studio to open the file at the given absolute path. Requires a connected Tableau Studio session; authorized by that session's loopback bearer token. The request body is JSON naming filePath.
    • POST /v<x>/app:openFile — open a local file by absolute path. API reference

Required arguments​

filePath​

Absolute path of the local file to open. Type: string. Must contain at least one character. A .twb or .twbx opens as a workbook. A datasource file (Excel, text, spatial, extract, .tds, and the like) attaches to the workbook already open in the session, and Tableau Studio creates a workbook first if none is open. A file type Tableau Studio cannot open is refused before the file is dispatched.

Example​

{ "filePath": "/Users/me/Sales.twbx" }
New window vs this session

When filePath points at a .twb or .twbx and a workbook is already open, Tableau Studio launches that file in a new window. This session stays bound to the original workbook: later reads still describe the first workbook, not the one just opened. Opening a datasource file does not start a new window — it attaches to the workbook this session already has.

Optional arguments​

session​

Identifier of the target Tableau Studio session. When omitted, the session is resolved automatically (for example, when exactly one Tableau Studio instance is connected).

Example​

"studio-1"

Session resolution does not guess

With no session given and no Tableau Studio instance running, or more than one running, the tool reports an error rather than picking one; the multiple-instance error lists the session IDs to choose from. A session that names an instance which is not among the running ones is refused the same way.

Notes and caveats​

  • A request that has been accepted but not finished is reported as such. When Tableau Studio answers before the open has settled, the result says the file was requested and is still being applied instead of claiming it completed.

Example results​

File opened​

{ "message": "Opened \"/Users/me/Sales.twbx\"." }

Accepted, still being applied​

{ "message": "Requested opening \"/Users/me/Sales.twbx\"; Desktop is still applying it." }
  • save-workbook — saves the session-bound open workbook in place, or a copy to an absolute path.
  • get-sheets — lists worksheets in the workbook this session is bound to, which remains the original workbook if open-file launched a second window.
  • get-xml — reads the structure of that same session-bound workbook.