# CLI Reference

Latchkey commands are organized into 4 categories:

1. Service discovery: List and inspect supported services
2. Authentication: Store and manage API credentials
3. Making requests: Execute authenticated curl commands
4. Setup: Configure browser support and agent integrations

## Service discovery

#### latchkey services list

List all supported third-party services.

Usage: `latchkey services list`

Example output:

```
Supported services: 
• aws
• discord
• github
• linear
• slack
• stripe 
...
```

#### latchkey services info

Show detailed information about a specific service.

Usage: `latchkey services info <service_name>`

Example: `latchkey services info slack`

Example output:

```
Service: slack API
Documentation: https://api.slack.com/web
Credentials Status: valid 
Authentication: Browser or manual 
Notes: Supports both browser-based login and manual token setup
```

> Tip: Use this command to check if your stored credentials are still valid. If the status shows invalid, re-authenticate with latchkey auth browser or latchkey auth set.

#### latchkey services register

Register a custom service for use with Latchkey. This enables two important use cases:

* **Self-hosted instances of known services** (e.g., a private GitLab): Register the instance as a new service that inherits behavior from the built-in service family.
* **Entirely new services**: Add basic Latchkey support for any HTTP API at runtime, without modifying Latchkey's source code.

Usage:

* Self-hosted instance: `latchkey services register <name> --service-family=<family> --base-api-url="<url>"`
* New service: `latchkey services register <name> --base-api-url="<url>"`

Examples:

* Register a self-hosted GitLab:

```
latchkey services register my-gitlab --service-family=gitlab --base-api-url="https://gitlab.example.com/api/v4/"
latchkey auth set my-gitlab -H "PRIVATE-TOKEN: <token>"
latchkey curl https://gitlab.example.com/api/v4/user
```

* Register a new service (e.g., Mastodon):

```
latchkey services register mastodon --base-api-url="https://mastodon.social/api/v1/"
latchkey auth set mastodon -H "Authorization: Bearer <your_access_token>"
latchkey curl https://mastodon.social/api/v1/timelines/public?limit=2
```

{% hint style="info" %}
User-registered services only support authentication via static curl arguments provided through `latchkey auth set`.
{% endhint %}

#### latchkey services deregister

Remove a previously registered custom service.

Usage: `latchkey services deregister <name>`

Example: `latchkey services deregister my-gitlab`

## Authentication

#### latchkey auth browser

Open a browser window, log in to the service, and automatically extract and store API credentials.

Usage: `latchkey auth browser <service_name>`

Example: `latchkey auth browser slack`

What happens:

1. Browser window opens with the service's login page
2. You log in using your normal credentials
3. Latchkey extracts API tokens from the browser session
4. Browser closes automatically
5. Credentials are encrypted and stored in \~/.latchkey

{% hint style="info" %}
This command is designed to be invoked by agents as well as humans. When an agent needs access to a service, it can run `latchkey auth browser <service_name>` to open a browser window for the user to log in. Once authentication is complete, the agent continues working with the stored credentials.
{% endhint %}

{% hint style="warning" %}
For some services, browser authentication involves automated steps beyond a simple login — such as navigating to developer settings, creating an app, or generating access keys. This may leave side effects in your account on that service. Review what was created after authenticating if you want to keep your account tidy.
{% endhint %}

#### latchkey auth set \<curl\_arguments>

Manually store API credentials for a service using curl arguments.

Usage: `latchkey auth set <service_name> <curl_arguments>`

Examples:

* Bearer token authentication: `latchkey auth set slack -H "Authorization: Bearer xoxb-your-token"`
* API key in header: `latchkey auth set github -H "Authorization: token ghp_your_token"`
* Multiple headers: `latchkey auth set stripe -H "Authorization: Bearer sk_test_..." -H "Stripe-Version: 2023-10-16"`

#### latchkey auth set-nocurl

Store credentials that can't be expressed as static curl arguments.

Some services require dynamic authentication (e.g., AWS request signing, tokens embedded in URLs). For these services, use set-nocurl.

Usage: `latchkey auth set-nocurl <service_name>`

Example (Telegram bot token): `latchkey auth set-nocurl telegram`

Latchkey will modify subsequent latchkey curl requests to inject the token correctly (e.g., into the URL path for Telegram).

#### latchkey auth clear \[service]

Remove stored credentials.

Usage:

* Clear credentials for a specific service: `latchkey auth clear <service_name>`
* Clear all stored credentials and browser state: `latchkey auth clear`

Example: `latchkey auth clear discord`

## Making requests

#### latchkey curl

Execute a curl command with automatic credential injection.

Usage: `latchkey curl <standard_curl_arguments>`

Latchkey:

1. Detects which service you're calling based on the URL
2. Injects the appropriate authentication headers or URL modifications
3. Passes all arguments directly to curl
4. Returns curl's output, exit code, and stderr unchanged

Examples:

* POST request to Slack:

`latchkey curl -X POST 'https://slack.com/api/conversations.create'`\
`-H 'Content-Type: application/json'`\
`-d '{"name":"something-urgent"}'`

* GET request to GitHub:

`latchkey curl https://api.github.com/user/repos`

* Linear GraphQL query:

`latchkey curl -X POST 'https://api.linear.app/graphql'`\
`-H 'Content-Type: application/json'`\
`-d '{"query":"{ viewer { id name } }"}'`

## Setup

#### latchkey ensure-browser

Discover and configure a browser for Latchkey to use with latchkey auth browser.

Usage: `latchkey ensure-browser`

What it does:

1. Searches for Chrome, Chromium, or Edge on your system
2. Configures Latchkey to use the found browser
3. Downloads Chromium via Playwright if no browser is found

#### latchkey skill-md

Generate a skill file for AI agent integration.

Usage: `latchkey skill-md`

This outputs a Markdown-formatted skill documentation to stdout.

Example integration:

* Claude Code:

```
mkdir -p ~/.claude/skills/latchkey
latchkey skill-md > ~/.claude/skills/latchkey/SKILL.md
```

* OpenCode:

```
mkdir -p ~/.opencode/skills/latchkey
latchkey skill-md > ~/.opencode/skills/latchkey/SKILL.md
```

* Codex:

```
mkdir -p ~/.codex/skills/latchkey
latchkey skill-md > ~/.codex/skills/latchkey/SKILL.md
```

This teaches your agent how to use Latchkey commands and when to prompt for authentication.

## Environment variables

Override default behavior with environment variables:

#### LATCHKEY\_DIRECTORY

Change where Latchkey stores credentials and browser state.

`export LATCHKEY_DIRECTORY="$HOME/.config/latchkey"`

{% hint style="info" %}
The default is `~/.latchkey`
{% endhint %}

#### LATCHKEY\_CURL

Specify a custom curl binary path.

`export LATCHKEY_CURL="/usr/local/bin/curl"`

#### LATCHKEY\_ENCRYPTION\_KEY

Override the encryption key (e.g., when no keyring is available).

`export LATCHKEY_ENCRYPTION_KEY="$(openssl rand -base64 32)"`

#### LATCHKEY\_DISABLE\_BROWSER

Disable browser-based authentication entirely.

`export LATCHKEY_DISABLE_BROWSER=1`

Commands that would trigger a browser login will fail with an error instead.

#### LATCHKEY\_KEYRING\_SERVICE\_NAME / LATCHKEY\_KEYRING\_ACCOUNT\_NAME

Customize keyring identifiers for storing the encryption password.

`export LATCHKEY_KEYRING_SERVICE_NAME="my-latchkey" export LATCHKEY_KEYRING_ACCOUNT_NAME="credentials"`

***

Access Latchkey here: <https://github.com/imbue-ai/latchkey>