Creating a dedicated Looker user

spectacles uses the Looker API to check out branches, activate development mode, inspect LookML, and run queries. If you are running spectacles locally or trying it out for the first time, feel free to use your own personal API credentials. In a production or continuous integration environment, we strongly recommend creating a dedicated Looker user for spectacles so you can limit permissions and avoid simultaneous access of Git branches from the website and from the API.

Once you create a new user in the Looker Admin > Users, you will need to generate API credentials and save the client ID and client secret.

Configuration options

There are three different ways to provide your API client ID and client secret to spectacles.

The following arguments can be passed directly via the command line, as environment variables, or as a .yml configuration file (in order of precedence).

Argument Name Description Environment Variable Required
--base-url The URL of your Looker instance, e.g. LOOKER_BASE_URL
--client-id The client ID of the Looker user that spectacles will authenticate as. LOOKER_CLIENT_ID
--client-secret The client secret of the Looker user that spectacles will authenticate as. LOOKER_CLIENT_SECRET
--port The port of your Looker instance’s API. The default is port 19999. LOOKER_PORT
--api-version The version of the Looker API to use. The default is version 3.1. LOOKER_API_VERSION
--config-file The path to an optional YAML config file.

Using a YAML file

The most convenient approach is to save your spectacles configuration as a .yml file. To do so, you will need to declare where your files is when you call spectacles, using the --config-file flag.

You can call the file whatever you want. In this example, we will create a looker_configuration.yml file:

client_id: HpB53crD3DMDkdJPCRc
client_secret: jDRSM6ZGG9D5WH3r5FynQ9c
spectacles connect --config-file looker_configuration.yml

Using command-line arguments

To declare arguments via the command line, simply pass them after the spectacles command:

spectacles connect --base-url --client-id HpB53crD3DMDkdJPCRc --client-secret jDRSM6ZGG9D5WH3r5FynQ9c

Using environment variables

You can set your arguments as environment variables. The environment variable names are in the table above. You can then run spectacles without declaring those arguments every time.


spectacles connect

Using multiple argument methods

If you would like to, you can mix and match the argument options listed above.

For example, you could use the .yml file above, but provide the port as a command line argument. Precedence for configuration arguments is: command line > environment variable > configuration file.

spectacles connect --config-file looker_configuration.yml --port 5432

Verbose mode

You can pass spectacles -v or --verbose to run at a debug logging level. This is helpful for debugging errors or getting a closer look at how spectacles is interacting with the Looker API.

👉 Next: Testing Your Connection