latchkey 2.4.3 → 2.5.0

package/README.md

@@ -1,5 +1,10 @@
 # Latchkey
 
+[![npm](https://img.shields.io/npm/v/latchkey?style=flat-square)](https://npmjs.com/package/your-pkg)
+[![CI](https://img.shields.io/github/actions/workflow/status/imbue-ai/latchkey/test.yml?style=flat-square)](https://github.com/imbue-ai/latchkey/actions)
+[![license](https://img.shields.io/npm/l/latchkey?style=flat-square)](LICENSE)
+[![downloads](https://img.shields.io/npm/dm/latchkey?style=flat-square)](https://npmjs.com/package/latchkey)
+
 Inject API credentials into local agent requests.
 
 ## Quick example

package/dist/skills/generic/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: latchkey
+description: Interact with third-party or self-hosted services (Slack, Google Workspace, Dropbox, GitHub, Linear, Coolify...) using their HTTP APIs on the user's behalf.
+compatibility: Requires node.js, curl and latchkey (npm install -g latchkey). A desktop/GUI environment is required for the browser functionality.
+---
+
+# Latchkey
+
+## Instructions
+
+Latchkey is a CLI tool that automatically injects credentials into curl commands. Credentials (mostly API tokens) can be either manually managed or, for some services, Latchkey can open a browser login pop-up window and extract API credentials from the session.
+
+Use this skill when the user asks you to work on their behalf with services that have HTTP APIs, like AWS, GitLab, Google Drive, Discord or others.
+
+Usage:
+
+1. **Use `latchkey curl`** instead of regular `curl` for supported services.
+2. **Pass through all regular curl arguments** - latchkey is a transparent wrapper.
+3. **Check for `latchkey services list`** to get a list of supported services. Use `--viable` to only show the currently configured ones.
+4. **Use `latchkey services info <service_name>`** to get information about a specific service (auth options, credentials status, API docs links, special requirements, etc.).
+5. **If necessary, ask the user to configure credentials first.** Tell the user to run `latchkey auth set` on the machine where latchkey is installed (using the setCredentialsExample from the `services info` command).
+6. **Alternatively, let the user log in with the browser.** If supported for the given service, run `latchkey auth browser <service_name>` to open a browser login pop-up window.
+7. **Look for the newest documentation of the desired public API online.** If using the `browser` auth command, avoid bot-only endpoints.
+8. **Do not initiate a new login if the credentials status is `valid` or `unknown`** - the user might just not have the necessary permissions for the action you're trying to do.
+
+
+## Examples
+
+### Make an authenticated curl request
+```bash
+latchkey curl [curl arguments]
+```
+
+### Creating a Slack channel
+```bash
+latchkey curl -X POST 'https://slack.com/api/conversations.create' \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"my-channel"}'
+```
+
+(Notice that `-H 'Authorization: Bearer` is not present in the invocation.)
+
+### Getting Discord user info
+```bash
+latchkey curl 'https://discord.com/api/v10/users/@me'
+```
+
+### Detect expired credentials and force a new login to Discord
+```bash
+latchkey services info discord  # Check the "credentialStatus" field - shows "invalid"
+latchkey auth browser discord
+latchkey curl 'https://discord.com/api/v10/users/@me'
+```
+
+Only do this when you notice that your previous call ended up not being authenticated (HTTP 401 or 403).
+
+### List usable services
+
+```bash
+latchkey services list --viable
+```
+
+Lists services that either have stored credentials or can be authenticated via a browser.
+
+### Get service-specific info
+```bash
+latchkey services info slack
+```
+
+Returns auth options, credentials status, and developer notes
+about the service. If `browser` is not present in the
+`authOptions` field, the service requires the user to directly
+set API credentials via `latchkey auth set` or `latchkey auth
+set-nocurl` before making requests.
+
+
+## Storing credentials
+
+Aside from the `latchkey auth browser` case, it is the user's responsibility to supply credentials.
+The user would typically do something like this:
+
+```bash
+latchkey auth set my-gitlab-instance -H "PRIVATE-TOKEN: <token>"
+```
+
+When credentials cannot be expressed as static curl arguments, the user would use the `set-nocurl` subcommand. For example:
+
+```bash
+latchkey auth set-nocurl aws <access-key-id> <secret-access-key>
+```
+
+If a service doesn't appear with the `--viable` flag, it may
+still be supported; the user just hasn't provided the
+credentials yet. `latchkey service info <service_name>` can be
+used to see how to provide credentials for a specific service.
+
+
+## Notes
+
+- All curl arguments are passed through unchanged
+- Return code, stdout and stderr are passed back from curl
+- Credentials are always stored encrypted and are never transmitted anywhere beyond the endpoints specified by the actual curl calls.
+
+## Currently supported services
+
+Latchkey currently offers varying levels of support for the
+following services: AWS, Calendly, Coolify, Discord, Dropbox, Figma, GitHub, GitLab,
+Gmail, Google Analytics, Google Calendar, Google Docs, Google Drive, Google Sheets,
+Linear, Mailchimp, Notion, Sentry, Slack, Stripe, Telegram, Umami, Yelp, Zoom, and more.
+
+### User-registered services
+
+Note for humans: users can also add limited support for new services
+at runtime using the `latchkey services register` command.

package/dist/skills/generic/latchkey/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: latchkey
+description: Interact with third-party or self-hosted services (Slack, Google Workspace, Dropbox, GitHub, Linear, Coolify...) using their HTTP APIs on the user's behalf.
+compatibility: Requires node.js, curl and latchkey (npm install -g latchkey). A desktop/GUI environment is required for the browser functionality.
+---
+
+# Latchkey
+
+## Instructions
+
+Latchkey is a CLI tool that automatically injects credentials into curl commands. Credentials (mostly API tokens) can be either manually managed or, for some services, Latchkey can open a browser login pop-up window and extract API credentials from the session.
+
+Use this skill when the user asks you to work on their behalf with services that have HTTP APIs, like AWS, GitLab, Google Drive, Discord or others.
+
+Usage:
+
+1. **Use `latchkey curl`** instead of regular `curl` for supported services.
+2. **Pass through all regular curl arguments** - latchkey is a transparent wrapper.
+3. **Check for `latchkey services list`** to get a list of supported services. Use `--viable` to only show the currently configured ones.
+4. **Use `latchkey services info <service_name>`** to get information about a specific service (auth options, credentials status, API docs links, special requirements, etc.).
+5. **If necessary, ask the user to configure credentials first.** Tell the user to run `latchkey auth set` on the machine where latchkey is installed (using the setCredentialsExample from the `services info` command).
+6. **Alternatively, let the user log in with the browser.** If supported for the given service, run `latchkey auth browser <service_name>` to open a browser login pop-up window.
+7. **Look for the newest documentation of the desired public API online.** If using the `browser` auth command, avoid bot-only endpoints.
+8. **Do not initiate a new login if the credentials status is `valid` or `unknown`** - the user might just not have the necessary permissions for the action you're trying to do.
+
+
+## Examples
+
+### Make an authenticated curl request
+```bash
+latchkey curl [curl arguments]
+```
+
+### Creating a Slack channel
+```bash
+latchkey curl -X POST 'https://slack.com/api/conversations.create' \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"my-channel"}'
+```
+
+(Notice that `-H 'Authorization: Bearer` is not present in the invocation.)
+
+### Getting Discord user info
+```bash
+latchkey curl 'https://discord.com/api/v10/users/@me'
+```
+
+### Detect expired credentials and force a new login to Discord
+```bash
+latchkey services info discord  # Check the "credentialStatus" field - shows "invalid"
+latchkey auth browser discord
+latchkey curl 'https://discord.com/api/v10/users/@me'
+```
+
+Only do this when you notice that your previous call ended up not being authenticated (HTTP 401 or 403).
+
+### List usable services
+
+```bash
+latchkey services list --viable
+```
+
+Lists services that either have stored credentials or can be authenticated via a browser.
+
+### Get service-specific info
+```bash
+latchkey services info slack
+```
+
+Returns auth options, credentials status, and developer notes
+about the service. If `browser` is not present in the
+`authOptions` field, the service requires the user to directly
+set API credentials via `latchkey auth set` or `latchkey auth
+set-nocurl` before making requests.
+
+
+## Storing credentials
+
+Aside from the `latchkey auth browser` case, it is the user's responsibility to supply credentials.
+The user would typically do something like this:
+
+```bash
+latchkey auth set my-gitlab-instance -H "PRIVATE-TOKEN: <token>"
+```
+
+When credentials cannot be expressed as static curl arguments, the user would use the `set-nocurl` subcommand. For example:
+
+```bash
+latchkey auth set-nocurl aws <access-key-id> <secret-access-key>
+```
+
+If a service doesn't appear with the `--viable` flag, it may
+still be supported; the user just hasn't provided the
+credentials yet. `latchkey service info <service_name>` can be
+used to see how to provide credentials for a specific service.
+
+
+## Notes
+
+- All curl arguments are passed through unchanged
+- Return code, stdout and stderr are passed back from curl
+- Credentials are always stored encrypted and are never transmitted anywhere beyond the endpoints specified by the actual curl calls.
+
+## Currently supported services
+
+Latchkey currently offers varying levels of support for the
+following services: AWS, Calendly, Coolify, Discord, Dropbox, Figma, GitHub, GitLab,
+Gmail, Google Analytics, Google Calendar, Google Docs, Google Drive, Google Sheets,
+Linear, Mailchimp, Notion, Sentry, Slack, Stripe, Telegram, Umami, Yelp, Zoom, and more.
+
+### User-registered services
+
+Note for humans: users can also add limited support for new services
+at runtime using the `latchkey services register` command.

package/dist/skills/openclaw/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: latchkey
+description: Interact with arbitrary third-party or self-hosted services (AWS, Slack, Google Drive, Dropbox, GitHub, GitLab, Linear, Coolify...) using their HTTP APIs.
+compatibility: Requires node.js, curl and latchkey (npm install -g latchkey).
+metadata: {"openclaw":{"emoji":"🔑","requires":{"bins":["latchkey"]},"install":[{"id":"node","kind":"node","package":"latchkey","bins":["latchkey"],"label":"Install Latchkey (npm)"}]}}
+---
+
+# Latchkey
+
+## Instructions
+
+Latchkey is a CLI tool that automatically injects credentials into curl commands. Credentials (mostly API tokens) need to be manually managed by the user.
+
+Use this skill when the user asks you to work with services that have HTTP APIs, like AWS, Coolify, GitLab, Google Drive, Discord or others.
+
+Usage:
+
+1. **Use `latchkey curl`** instead of regular `curl` for supported services.
+2. **Pass through all regular curl arguments** - latchkey is a transparent wrapper.
+3. **Check for `latchkey services list`** to get a list of supported services. Use `--viable` to only show the currently configured ones.
+4. **Use `latchkey services info <service_name>`** to get information about a specific service (auth options, credentials status, API docs links, special requirements, etc.).
+5. **If necessary, ask the user to configure credentials first.** Tell the user to run `latchkey auth set` on the machine where latchkey is installed (using the setCredentialsExample from the `services info` command).
+6. **Look for the newest documentation of the desired public API online.**
+7. **Do not initiate a new login if the credentials status is `valid` or `unknown`** - the user might just not have the necessary permissions for the action you're trying to do.
+
+
+## Examples
+
+### Make an authenticated curl request
+```bash
+latchkey curl [curl arguments]
+```
+
+### Creating a Slack channel
+```bash
+latchkey curl -X POST 'https://slack.com/api/conversations.create' \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"my-channel"}'
+```
+
+(Notice that `-H 'Authorization: Bearer` is not present in the invocation.)
+
+### Getting Discord user info
+```bash
+latchkey curl 'https://discord.com/api/v10/users/@me'
+```
+
+### Detect expired credentials
+```bash
+latchkey services info discord  # Check the "credentialStatus" field - shows "invalid"
+```
+
+### List usable services
+
+```bash
+latchkey services list --viable
+```
+
+Lists services that have stored credentials.
+
+### Get service-specific info
+```bash
+latchkey services info slack
+```
+
+Returns auth options, credentials status, and developer notes
+about the service.
+
+
+## Storing credentials
+
+It is the user's responsibility to supply credentials. The user would typically do something like this:
+
+```bash
+latchkey auth set my-gitlab-instance -H "PRIVATE-TOKEN: <token>"
+```
+
+When credentials cannot be expressed as static curl arguments, the user would use the `set-nocurl` subcommand. For example:
+
+```bash
+latchkey auth set-nocurl aws <access-key-id> <secret-access-key>
+```
+
+If a service doesn't appear with the `--viable` flag, it may
+still be supported; the user just hasn't provided the
+credentials yet. `latchkey service info <service_name>` can be
+used to see how to provide credentials for a specific service.
+
+
+## Notes
+
+- All curl arguments are passed through unchanged
+- Return code, stdout and stderr are passed back from curl
+- Credentials are always stored encrypted and are never transmitted anywhere beyond the endpoints specified by the actual curl calls.
+
+## Currently supported services
+
+Latchkey currently offers varying levels of support for the
+following services: AWS, Calendly, Coolify, Discord, Dropbox, Figma, GitHub, GitLab,
+Gmail, Google Analytics, Google Calendar, Google Docs, Google Drive, Google Sheets,
+Linear, Mailchimp, Notion, Sentry, Slack, Stripe, Telegram, Umami, Yelp, Zoom, and more.
+
+### User-registered services
+
+Note for humans: users can also add limited support for new services
+at runtime using the `latchkey services register` command.

package/dist/skills/openclaw/latchkey/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: latchkey
+description: Interact with arbitrary third-party or self-hosted services (AWS, Slack, Google Drive, Dropbox, GitHub, GitLab, Linear, Coolify...) using their HTTP APIs.
+compatibility: Requires node.js, curl and latchkey (npm install -g latchkey).
+metadata: {"openclaw":{"emoji":"🔑","requires":{"bins":["latchkey"]},"install":[{"id":"node","kind":"node","package":"latchkey","bins":["latchkey"],"label":"Install Latchkey (npm)"}]}}
+---
+
+# Latchkey
+
+## Instructions
+
+Latchkey is a CLI tool that automatically injects credentials into curl commands. Credentials (mostly API tokens) need to be manually managed by the user.
+
+Use this skill when the user asks you to work with services that have HTTP APIs, like AWS, Coolify, GitLab, Google Drive, Discord or others.
+
+Usage:
+
+1. **Use `latchkey curl`** instead of regular `curl` for supported services.
+2. **Pass through all regular curl arguments** - latchkey is a transparent wrapper.
+3. **Check for `latchkey services list`** to get a list of supported services. Use `--viable` to only show the currently configured ones.
+4. **Use `latchkey services info <service_name>`** to get information about a specific service (auth options, credentials status, API docs links, special requirements, etc.).
+5. **If necessary, ask the user to configure credentials first.** Tell the user to run `latchkey auth set` on the machine where latchkey is installed (using the setCredentialsExample from the `services info` command).
+6. **Look for the newest documentation of the desired public API online.**
+7. **Do not initiate a new login if the credentials status is `valid` or `unknown`** - the user might just not have the necessary permissions for the action you're trying to do.
+
+
+## Examples
+
+### Make an authenticated curl request
+```bash
+latchkey curl [curl arguments]
+```
+
+### Creating a Slack channel
+```bash
+latchkey curl -X POST 'https://slack.com/api/conversations.create' \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"my-channel"}'
+```
+
+(Notice that `-H 'Authorization: Bearer` is not present in the invocation.)
+
+### Getting Discord user info
+```bash
+latchkey curl 'https://discord.com/api/v10/users/@me'
+```
+
+### Detect expired credentials
+```bash
+latchkey services info discord  # Check the "credentialStatus" field - shows "invalid"
+```
+
+### List usable services
+
+```bash
+latchkey services list --viable
+```
+
+Lists services that have stored credentials.
+
+### Get service-specific info
+```bash
+latchkey services info slack
+```
+
+Returns auth options, credentials status, and developer notes
+about the service.
+
+
+## Storing credentials
+
+It is the user's responsibility to supply credentials. The user would typically do something like this:
+
+```bash
+latchkey auth set my-gitlab-instance -H "PRIVATE-TOKEN: <token>"
+```
+
+When credentials cannot be expressed as static curl arguments, the user would use the `set-nocurl` subcommand. For example:
+
+```bash
+latchkey auth set-nocurl aws <access-key-id> <secret-access-key>
+```
+
+If a service doesn't appear with the `--viable` flag, it may
+still be supported; the user just hasn't provided the
+credentials yet. `latchkey service info <service_name>` can be
+used to see how to provide credentials for a specific service.
+
+
+## Notes
+
+- All curl arguments are passed through unchanged
+- Return code, stdout and stderr are passed back from curl
+- Credentials are always stored encrypted and are never transmitted anywhere beyond the endpoints specified by the actual curl calls.
+
+## Currently supported services
+
+Latchkey currently offers varying levels of support for the
+following services: AWS, Calendly, Coolify, Discord, Dropbox, Figma, GitHub, GitLab,
+Gmail, Google Analytics, Google Calendar, Google Docs, Google Drive, Google Sheets,
+Linear, Mailchimp, Notion, Sentry, Slack, Stripe, Telegram, Umami, Yelp, Zoom, and more.
+
+### User-registered services
+
+Note for humans: users can also add limited support for new services
+at runtime using the `latchkey services register` command.

package/dist/src/skillMd.js

@@ -7,13 +7,13 @@ async function getSkillMdPath() {
     try {
         // @ts-expect-error - Bun-specific import attribute
         // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-        const mod = await import('../integrations/SKILL.md', {
+        const mod = await import('../skills/generic/latchkey/SKILL.md', {
             with: { type: 'text' },
         });
         return mod.default;
     }
     catch {
-        return resolve(import.meta.dirname, '../integrations/SKILL.md');
+        return resolve(import.meta.dirname, '../skills/generic/latchkey/SKILL.md');
     }
 }
 //# sourceMappingURL=skillMd.js.map

package/dist/src/skillMd.js.map

@@ -1 +1 @@
-{"version":3,"file":"skillMd.js","sourceRoot":"","sources":["../../src/skillMd.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,OAAO,YAAY,CAAC,MAAM,cAAc,EAAE,EAAE,OAAO,CAAC,CAAC;AACvD,CAAC;AAED,KAAK,UAAU,cAAc;IAC3B,IAAI,CAAC;QACH,mDAAmD;QACnD,mEAAmE;QACnE,MAAM,GAAG,GAAwB,MAAM,MAAM,CAAC,0BAA0B,EAAE;YACxE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;SACvB,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,OAAO,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,0BAA0B,CAAC,CAAC;IAClE,CAAC;AACH,CAAC"}
+{"version":3,"file":"skillMd.js","sourceRoot":"","sources":["../../src/skillMd.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,OAAO,YAAY,CAAC,MAAM,cAAc,EAAE,EAAE,OAAO,CAAC,CAAC;AACvD,CAAC;AAED,KAAK,UAAU,cAAc;IAC3B,IAAI,CAAC;QACH,mDAAmD;QACnD,mEAAmE;QACnE,MAAM,GAAG,GAAwB,MAAM,MAAM,CAAC,qCAAqC,EAAE;YACnF,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;SACvB,CAAC,CAAC;QACH,OAAO,GAAG,CAAC,OAAO,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,qCAAqC,CAAC,CAAC;IAC7E,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "latchkey",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "description": "A CLI tool that injects API credentials into curl requests to third-party services",
   "author": "Imbue <hynek@imbue.com>",
   "repository": {
@@ -24,7 +24,7 @@
   ],
   "scripts": {
     "prepublishOnly": "npm run build",
-    "build": "tsc && node -e \"require('fs').cpSync('integrations', 'dist/integrations', {recursive:true})\" ",
+    "build": "tsc && node -e \"require('fs').cpSync('skills', 'dist/skills', {recursive:true})\" ",
     "dev": "tsc --watch",
     "lint": "eslint src tests scripts",
     "lint:fix": "eslint src tests scripts --fix",
@@ -43,7 +43,8 @@
     "credentials",
     "authentication",
     "agents",
-    "imbue"
+    "imbue",
+    "pi-package"
   ],
   "license": "MIT",
   "engines": {
@@ -63,5 +64,8 @@
     "typescript": "^5.3.0",
     "typescript-eslint": "^8.53.1",
     "vitest": "^4.0.18"
+  },
+  "pi": {
+    "skills": ["./skills/generic"]
   }
 }