Skip to main content
An agent secret stores an API key, password, or token. Sign in as the agent that will use it, or use --agent <agent> with an account login.

​
1. Choose where the credential belongs

Before storing it, check the agent and workspace with artil auth status.
In a team workspace, members who can access the agent can reveal, change, and delete its secrets. In a personal workspace, only the owner and clients authorized to act as the agent have access.
Store credentials meant for this agent and the people who can access it. Names become environment variable names, such as SERVICE_API_KEY.

​
2. Store the value

In a terminal, omit the value to enter it without showing what you type:
Check that the list includes SERVICE_API_KEY. It shows who last set the value and when, keeping the value hidden. Running set again replaces it.
Pipe that command’s output directly into artil secrets set SERVICE_API_KEY. This keeps the key out of the command text and shell history.If that command produces JSON, select a field with --json-path .token or a nested path such as --json-path '.data.items[0].key'.Add --json for JSON output. With this flag, supply or pipe the value; the CLI returns an error if it would need to prompt for one.
Names use letters, digits, and underscores and cannot begin with a digit. Names such as PATH and HOME are reserved. Values must contain at least one character. Multiline values are accepted, but some clients cannot load them.

​
3. Choose where to use it

Linking copies all of the agent’s secrets to the client or file you choose. Link only places that should have access to all of them. artil init already links the local client it connects, so check artil secrets list before adding another link. The Claude Code plugin and Pi extension do not link secrets as part of their installation.
This installs a session-start hook in your user-level Claude Code configuration, which applies across projects. Claude’s Bash commands load the linked agent’s secrets from a private script. Linking another agent here replaces the previous link.Start a new Claude Code session after first linking. Programs launched by its Bash tool can then use $SERVICE_API_KEY without putting the value into the conversation.
Check that artil secrets list shows the client or file you linked. Fix any reported linking errors, then run artil secrets pull to try again. Use the saved key to make a request to the service and check that it succeeds. Programs that receive a secret through their environment can read its value. Keep those values out of logs and conversations.

​
Keep it working

set and remove refresh the agent’s linked destinations on this machine. After changing a value in the app or on another machine, run:
Run pull each time you need changes made elsewhere. Claude Code’s hook also tries to refresh secrets when a session starts. If the hook is already active, the next Bash command can use values updated by pull. Restart other programs that read their environment only at startup.If storing succeeds but updating a linked destination fails, the command reports the error and exits with a nonzero status. Fix the link and pull again.
The command copies the value to your clipboard without printing it.
This deletes the stored value from Artil and refreshes this machine’s links. Other machines need to refresh their copies. Deleting a stored API key does not revoke it at the service that issued it; revoke it there to end access.