Keyco Skill

This skill uses the Keyco CLI to manage assets (DUBs), workflows, lifecycle events, users, notifications, and analytics through the Keyco platform (api.qrdub.com).

When to Use This Skill

Invoke this skill when the user:

• Asks about Keyco assets, DUBs, or inventory
• Needs to look up a specific asset by UUID
• Wants to check asset lifecycle events, maintenance, or compliance
• Requests workflow status, asset assignments, or utilization reports
• Asks for analytics (weekly digest, stale assets, summaries)
• Wants to manage notifications, groups, or API keys
• Mentions api.qrdub.com, keyco.io, kc_live_*, or the keyco CLI
• Wants to script asset operations (bulk ops, CI/CD automation)

Prerequisites

Before running any command, verify the CLI is installed and configured:

1. Check if keyco is on PATH: which keyco

2. Check configuration: keyco status

3. If either check fails, run the setup script — it handles install + configure in one shot:

   bash scripts/setup-keyco.sh
   

   The script will:

   • Install @keyco/cli globally via npm if missing (falling back to sudo npm if needed)
   • Skip install if already present
   • Walk the user through keyco configure if no valid API key is set
   • Verify connectivity at the end

   Always offer to run this script before failing — don't ask the user to manually install or configure.

Core Workflow

1. Identify the user's intent

Map their request to one of the Keyco domains:

2. Run commands with --output json for programmatic parsing

Always append --output json when you need to parse or transform the data. Use --output table only when displaying directly to the user.

3. Handle errors

• 401 / 403: API key missing, expired, or lacking required scope — tell the user to run keyco configure or create a key with the needed scope
• 404: Resource doesn't exist — double-check the UUID with the user
• 429: Rate limited — back off and retry
• Connection errors: Check keyco status to verify reachability

4. Summarize results for the user

Don't just dump raw JSON — extract the key fields and present them clearly. Offer follow-up actions (e.g., "Want me to check its location history too?").

Data Integrity — IMPORTANT

The following operations have been intentionally removed from the Keyco CLI because they bypass authoritative scan/heartbeat events and break the audit trail:

• Manual DUB location updates
• Marking workflows complete out-of-band
• Advancing workflow steps without a verified DUB scan

Never try to work around these restrictions. If the user asks to "set" or "update" a DUB's location or manually complete a workflow, explain that these actions must happen via the physical scan/event flow (QR scan, NFC tap, BLE heartbeat) to preserve audit integrity. Direct them to [email protected] if they need an override for legitimate reasons.

Output Format

When presenting asset data to the user:

Asset: \x3Cdubname>
UUID: \x3Cuuid>
Type: \x3CQR | Pro | Active | Virtual>
Status: \x3Cactive | inactive>
Group: \x3Cgroup name>
Assigned to: \x3Cuser email or "Unassigned">
Last seen: \x3Ctimestamp>

When running analytics, lead with the top-line numbers, then break down by category.

Examples

User: "What assets does [email protected] have?" → keyco user list --output json to find her user ID, then → keyco user assigned-dubs --user-id \x3CUUID> --output json → Summarize: "Alice has N assets assigned: [list]"

User: "Create a maintenance event for DUB ee6f2f42-31b1-4f90-9440-e91fb02ac7c4 due next Friday" → Compute the absolute date from "next Friday" → keyco lifecycles create --event-type MAINTENANCE --name "Maintenance" --assigned-dub ee6f2f42-31b1-4f90-9440-e91fb02ac7c4 --due-date 2026-04-24 → Confirm creation to the user with the returned event ID

User: "Show me this week's analytics" → keyco analytics weekly-digest --output json → Summarize top-line metrics (total assets, active workflows, open lifecycle events, utilization %)

User: "Find any stale assets" → keyco analytics stale-assets --output json → Report the count and list the first few, offering to create maintenance events or reassign them

User: "Import 50 assets from this CSV" → Explain that bulk CSV import goes through POST /api/imports/upload (not yet in CLI) — suggest they use the dashboard at https://dashboard.qrdub.com or loop over keyco lifecycles create / asset endpoints individually

Scripting Recipes

For multi-step tasks, compose commands with standard shell tools:

# Export all DUBs as JSON
keyco dub list --size 1000 --output json > all-dubs.json

# Find assets with no assigned user
keyco user unassigned-dubs --output json | jq '.[] | .uuid'

# Stale asset count for CI
STALE=$(keyco analytics stale-assets --output json | jq '.totalElements')
echo "$STALE stale assets detected"

References

• Full CLI command reference
• API scope reference
• Data integrity guidelines
• Keyco docs: https://docs.qrdub.com
• Keyco dashboard: https://dashboard.qrdub.com