|
| 1 | +# Credentials |
| 2 | + |
| 3 | +GPTScript supports credential provider tools. These tools can be used to fetch credentials from a secure location (or |
| 4 | +directly from user input) and conveniently set them in the environment before running a script. |
| 5 | + |
| 6 | +## Writing a Credential Provider Tool |
| 7 | + |
| 8 | +A credential provider tool looks just like any other GPTScript, with the following caveats: |
| 9 | +- It cannot call the LLM and must run a command. |
| 10 | +- It must print contents to stdout in the format `{"env":{"ENV_VAR_1":"value1","ENV_VAR_2":"value2"}}`. |
| 11 | +- Any args defined on the tool will be ignored. |
| 12 | + |
| 13 | +Here is a simple example of a credential provider tool that uses the builtin `sys.prompt` to ask the user for some input: |
| 14 | + |
| 15 | +```yaml |
| 16 | +# my-credential-tool.gpt |
| 17 | +name: my-credential-tool |
| 18 | + |
| 19 | +#!/usr/bin/env bash |
| 20 | + |
| 21 | +output=$(gptscript -q --cache=false sys.prompt '{"message":"Please enter your fake credential.","fields":"credential","sensitive":"true"}') |
| 22 | +credential=$(echo $output | jq -r '.credential') |
| 23 | +echo "{\"env\":{\"MY_ENV_VAR\":\"$credential\"}}" |
| 24 | +``` |
| 25 | + |
| 26 | +## Using a Credential Provider Tool |
| 27 | + |
| 28 | +Continuing with the above example, this is how you can use it in a script: |
| 29 | + |
| 30 | +```yaml |
| 31 | +credentials: my-credential-tool.gpt |
| 32 | + |
| 33 | +#!/usr/bin/env bash |
| 34 | + |
| 35 | +echo "The value of MY_ENV_VAR is $MY_ENV_VAR" |
| 36 | +``` |
| 37 | + |
| 38 | +When you run the script, GPTScript will call the credential provider tool first, set the environment variables from its |
| 39 | +output, and then run the script body. The credential provider tool is called by GPTScript itself. GPTScript does not ask the |
| 40 | +LLM about it or even tell the LLM about the tool. |
| 41 | + |
| 42 | +If GPTScript has called the credential provider tool in the same context (more on that later), then it will use the stored |
| 43 | +credential instead of fetching it again. |
| 44 | + |
| 45 | +You can also specify multiple credential tools for the same script: |
| 46 | + |
| 47 | +```yaml |
| 48 | +credentials: credential-tool-1.gpt, credential-tool-2.gpt |
| 49 | + |
| 50 | +(tool stuff here) |
| 51 | +``` |
| 52 | + |
| 53 | +## Storing Credentials |
| 54 | + |
| 55 | +By default, credentials are automatically stored in a config file at `$XDG_CONFIG_HOME/gptscript/config.json`. |
| 56 | +This config file also has another parameter, `credsStore`, which indicates where the credentials are being stored. |
| 57 | + |
| 58 | +- `file` (default): The credentials are stored directly in the config file. |
| 59 | +- `osxkeychain`: The credentials are stored in the macOS Keychain. |
| 60 | + |
| 61 | +In order to use `osxkeychain` as the credsStore, you must have the `gptscript-credential-osxkeychain` executable |
| 62 | +available in your PATH. There will probably be better packaging for this in the future, but for now, you can build it |
| 63 | +from the [repo](https://github.com/gptscript-ai/gptscript-credential-helpers). |
| 64 | + |
| 65 | +There will likely be support added for other credential stores in the future. |
| 66 | + |
| 67 | +:::note |
| 68 | +Credentials received from credential provider tools that are not on GitHub (such as a local file) will not be stored |
| 69 | +in the credentials store. |
| 70 | +::: |
| 71 | + |
| 72 | +## Credential Contexts |
| 73 | + |
| 74 | +Each stored credential is uniquely identified by the name of its provider tool and the name of its context. A credential |
| 75 | +context is basically a namespace for credentials. If you have multiple credentials from the same provider tool, you can |
| 76 | +switch between them by defining them in different credential contexts. The default context is called `default`, and this |
| 77 | +is used if none is specified. |
| 78 | + |
| 79 | +You can set the credential context to use with the `--credential-context` flag when running GPTScript. For |
| 80 | +example: |
| 81 | + |
| 82 | +```bash |
| 83 | +gptscript --credential-context my-azure-workspace my-azure-script.gpt |
| 84 | +``` |
| 85 | + |
| 86 | +Any credentials fetched for that script will be stored in the `my-azure-workspace` context. If you were to call it again |
| 87 | +with a different context, you would be able to give it a different set of credentials. |
| 88 | + |
| 89 | +## Listing and Deleting Stored Credentials |
| 90 | + |
| 91 | +The `gptscript credential` command can be used to list and delete stored credentials. Running the command with no |
| 92 | +`--credential-context` set will use the `default` credential context. You can also specify that it should list |
| 93 | +credentials in all contexts with `--all-contexts`. |
| 94 | + |
| 95 | +You can delete a credential by running the following command: |
| 96 | + |
| 97 | +```bash |
| 98 | +gptscript credential delete --credential-context <credential context> <credential tool name> |
| 99 | +``` |
0 commit comments