Profiles

The Hatchet CLI supports managing multiple Hatchet instances and tenants using named profiles. This feature makes it easy to switch between different environments, such as development, staging, and production.

Creating a Profile

You can create a new profile using the hatchet profile add command. You will need to provide a Hatchet API token for the profile.

hatchet profile add

This command will prompt you to enter the API token followed by the profile name. You can also provide these as flags:

hatchet profile add --name [name] --token [token]

Listing Profiles

You can list all the profiles you have configured using the hatchet profile list command:

hatchet profile list

This will display all configured profiles, with the default profile marked with (default) if one is set.

Setting a Default Profile

You can set a profile as the default using the hatchet profile set-default command. The default profile will be automatically used when no profile is specified with the --profile flag.

When no default is configured, hatchet server start sets the profile it creates as the default. Commands that take the --profile flag also use the only configured profile without prompting.

# Set default profile interactively (prompts for selection)
hatchet profile set-default

# Set a specific profile as default
hatchet profile set-default --name [name]

Once a default profile is set, you can run commands without specifying the --profile flag:

# Uses the default profile
hatchet worker dev

To unset the default profile:

hatchet profile unset-default

Using a Profile

To use a specific profile for your Hatchet CLI commands, you can specify the profile name using the --profile flag. This overrides the default profile if one is set.

hatchet worker dev --profile [name]

Updating a Profile

You can update an existing profile using the hatchet profile update command. This allows you to change the API token associated with a profile.

hatchet profile update

Deleting a Profile

You can delete a profile using the hatchet profile remove command:

hatchet profile remove

If you remove a profile that is set as the default, the default profile setting will be automatically cleared.

Where Tokens Are Stored

Profile metadata lives in ~/.hatchet/profiles.yaml. API tokens are stored in the system secret store instead of that file: the macOS Keychain, Windows Credential Manager, or the Secrets Service on Linux (GNOME Keyring, KWallet). profiles.yaml then contains no credentials, so it is safe to inspect, back up, or sync.

Profiles created by older CLI versions keep their tokens in profiles.yaml. The next time you run any command, the CLI moves them into the secret store automatically and prints a one-line note. Nothing is ever written back to profiles.yaml in plain text.

When no secret store is available, for example on a headless Linux server, in a container, or in CI, the CLI falls back to keeping tokens in profiles.yaml and prints a warning on every command. hatchet profile list and hatchet profile show also mark any profile whose token is stored in plain text.

To get a token out again, for example to configure a worker, use the read-only commands rather than the file:

# Shell exports for the SDKs
eval "$(hatchet profile env --name [name])"

# Print the full token
hatchet profile show --name [name] --show-token