@deerdesign/deertools

Official DeerTools CLI: Secure, scoped authentication and AI agent access for DeerTools product APIs.

Log in once from your computer, and grant your AI coding agent (Antigravity, Cursor, Claude Code, Lovable, CLI agents) access to DeerTools APIs on your behalf, scoped strictly to your permissions, with zero credentials exposed in URLs.

Supported Products

(Both English names like catalog, estimate, deliveries, skills and legacy Polish names like katalog, kosztorys, dostawy, umiejetnosci are supported interchangeably).

Installation

Requires Node.js ≥ 18. Zero runtime dependencies.

Option 1: Run instantly with npx (No installation needed)

npx -y @deerdesign/deertools@latest login catalog

Option 2: Install globally

npm install -g @deerdesign/deertools

This installs both the deertools binary and the convenient short alias deer:

deertools --help
# or
deer whoami

Authentication (OAuth 2.1 + PKCE S256)

DeerTools CLI implements the official OAuth 2.1 Authorization Code grant with PKCE (RFC 8252, RFC 8414):

# Log in to a single product with read-only access (default):
deertools login catalog

# Log in to other products (in English or Polish):
deertools login estimate         # or: deertools login kosztorys
deertools login deliveries       # or: deertools login dostawy
deertools login supplier
deertools login rendermind
deertools login skills           # or: deertools login hub

# Request read + write scopes:
deertools login catalog --write
deertools login skills --write

# Interactive login across all 6 products sequentially:
deertools login all

# Check current authentication status and expiration:
deertools whoami

# Check status in machine-readable JSON format:
deertools whoami --json

# Revoke local credentials:
deertools logout catalog

How it works under the hood

1. RFC 8414 Discovery: The CLI queries /.well-known/oauth-authorization-server on the product host to discover authorization and token endpoints.
2. Loopback Server: The CLI starts an ephemeral HTTP server on 127.0.0.1:<random-port> and generates a cryptographically secure PKCE code verifier and S256 challenge.
3. Browser Consent: The user's default browser opens to the product's /oauth/authorize page. The user authenticates (Microsoft SSO / SSO / Magic Link) and approves the requested scopes.
4. Single-Use Authorization Code: The browser redirects to the loopback server with a short-lived authorization code (60-second TTL). No keys or tokens ever appear in query strings.
5. Direct Exchange: The CLI sends a direct POST to the product's token endpoint (/oauth-token) with the code verifier.
6. Local Storage: The product issues a scoped API key (deer_<product>_live_...) valid for 90 days. The CLI persists it in ~/.deertools/credentials.json with strict POSIX file permissions (0600).

AI Agent Integration & Usage

1. Inspect Documentation & Specifications

# Read high-level llms.txt (public overview and authentication instructions):
deertools docs catalog
deertools docs rendermind

# Fetch full OpenAPI 3.0 JSON specification:
deertools docs catalog openapi

# List all available endpoints with required scopes:
deertools endpoints catalog

2. Invoke Product APIs

The CLI handles authorization headers automatically, rejecting any requests to non-whitelisted hosts:

# Call GET endpoint:
deertools api catalog GET /api/v1/products --query category=flooring

# Call POST endpoint with JSON payload:
deertools api rendermind POST /api/v1/visualizations --data '{"prompt":"Modern Scandinavian kitchen"}'

# Read payload from file:
deertools api rendermind POST /api/v1/visualizations --data-file request.json

3. Developer & Environment Utilities

DeerTools CLI focuses strictly on authentication, Remote MCP orchestration, and DeerSkills Hub management. Domain calculations and business logic are hosted directly on the product platforms (Kosztorys, Katalog, Dostawy, Supplier Hub, RenderMind) and accessed via their own REST APIs and Remote MCP endpoints.

# 1. Environment & API Doctor:
deertools doctor
deertools doctor --json

# 2. Shell Autocompletion (Zsh, Bash, Fish):
deertools completion install      # automatically configures ~/.zshrc or ~/.bashrc

# 3. BaseLinker Hub & MCP Proxy:
deertools baselinker auth <X-BLToken>           # Save BaseLinker token to credentials.json
deertools baselinker test                       # Test authorization and list product catalogs
deertools baselinker serve --port 3456          # Launch local Web UI dashboard + MCP SSE server
deertools baselinker mcp                        # Stdio MCP bridge (Cursor / Claude Desktop)
deertools baselinker sync-schema                # Download and refresh 204 API methods from api.baselinker.com
deertools baselinker search "relations"         # Search BaseLinker methods and parameter schemas
deertools baselinker call getOrders             # Direct API method execution from terminal
deertools baselinker catalog search 105 "oak"   # Search products in BaseLinker catalog

# 4. Local Stdio MCP Bridge (for Claude Desktop, Ollama, local LLM tools):
deertools mcp serve

# 5. Audit Log:
deertools audit --limit 25
deertools audit --clear

# 6. Multi-Profile Management:
deertools profile list
deertools profile use staging

# 7. AI Agent Skills (DeerSkills Hub):
deertools skill list                         # View list of skills with installation status across agents
deertools skill sync                         # Pull and update skills from Hub (protects local changes)
deertools sync --push                        # Full two-way sync: pull updates + push newer local skills to Hub
deertools skill install --all                # Alias for skill sync (full team synchronization)
deertools skill install deer-kosztorys       # Install specific skill to detected AI agent environments
deertools skill install deer-kosztorys --version 1.0.0
deertools skill search "pricing"             # Search skills by keyword, tag, or description
deertools skill push ./my-skill              # Publish new version with automated secret scanning
deertools skill push ./my-skill --tags "pricing, margins, design" # Attach tags upon publish
deertools skill push ./my-skill --team architects # Publish directly to specific team space
deertools skill share my-skill --team architects   # Share private skill with team members
deertools skill share my-skill --private           # Revoke sharing (private to author only)
deertools skill update deer-kosztorys        # Update installed skill to latest Hub version
deertools skill update                       # Update all installed skills across agents
deertools skill promote my-skill             # Submit promotion request to company-wide global registry

# 8. Team Management:
deertools team list                          # List teams, member counts, and assigned skills
deertools team members architects            # List members and roles in the architects team
deertools team add architects [email protected]   # Add user to team (member role)
deertools team add architects [email protected] --role lead # Add team lead
deertools team remove architects [email protected] # Remove member from team
deertools team create "Interior Designers" --slug designers # Create new organization team

# 9. AI Agent MCP Registry & Configuration:
deertools mcp list                           # List available MCP servers across the ecosystem
deertools mcp config                         # Print JSON MCP configuration for manual pasting
deertools mcp install                        # Automatically write & update MCP config across ALL 7 agent targets
deertools doctor                             # Verify MCP connectivity, auth tokens and client config files

AI Agent MCP Configuration & Tooling (Cursor, Antigravity, Claude)

@deerdesign/deertools provides 7 official MCP servers covering the complete Deer Design ecosystem:

1. deer-estimate: Floor plan PDF analysis, kitchen detection, interior cost calculations.
2. deer-catalog: 17k+ finishing materials (Smart/Modern/High Life), technical specs, filtering.
3. deer-deliveries: Site delivery tracking, supplier shipments, warehouse WZ generation.
4. deer-supplier: Supplier orders, purchase discounts, sales markups, commercial terms.
5. deer-rendermind: Interior rendering, pCon CAD visualization, product photorealistic renders.
6. deer-baselinker: Full BaseLinker catalog CRUD, pricing batch updates, Smart Cache.
7. deer-skills: DeerSkills Hub registry, skill search, download, and review pipelines.

1. Automatic Zero-Config Setup (Recommended)

You don't need to manually edit JSON files. Simply log in or run:

deertools login all    # Automatically logs in and syncs MCP configs across all clients
# or at any time:
deertools mcp install  # Re-generates and writes configuration to all 7 targets

deertools mcp install automatically discovers and writes to all 7 supported AI environments:

Verify all clients at any time with:

deertools doctor

2. Manual Configuration & Claude Integration Details

If configuring manually or adding to existing setups:

A. Project-level .mcp.json (Recommended for Claude Code & Cowork)

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "deer-rendermind": {
      "command": "/Users/<your-user>/.local/bin/deertools",
      "args": ["rendermind", "mcp"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/<your-user>/.local/bin"
      }
    },
    "deer-baselinker": {
      "command": "/Users/<your-user>/.local/bin/deertools",
      "args": ["baselinker", "mcp"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/<your-user>/.local/bin"
      }
    },
    "deer-catalog": {
      "url": "https://ftzaobeixglnssemugjf.supabase.co/functions/v1/catalog-mcp",
      "headers": {
        "x-api-key": "<your-catalog-key>",
        "Authorization": "Bearer <your-catalog-key>"
      }
    },
    "deer-estimate": {
      "url": "https://vlemuxlubrowuuxpgllk.supabase.co/functions/v1/estimate-mcp",
      "headers": {
        "x-api-key": "<your-estimate-key>",
        "Authorization": "Bearer <your-estimate-key>"
      }
    }
  }
}

[!IMPORTANT] Key Rules for Claude Desktop & Claude Code:

1. PATH Inheritance on macOS: Desktop GUI applications (like Claude Desktop) do NOT inherit your terminal's shell $PATH (~/.local/bin, /usr/local/bin). Always specify the absolute binary path (e.g. ~/.local/bin/deertools) and include the env.PATH block as shown above so node and child processes can be spawned without errors.
2. Project Trust Dialog: When opening a workspace with a project-level .mcp.json, Claude displays a security consent prompt ("Allow MCP servers from .mcp.json?"). You must click Allow / Always Allow to activate the tools.
3. Session Restart Required: MCP server tools are registered strictly when a conversation session is initialized. If you configure MCP while a session is already active, start a New Chat (Cmd + N) or restart the Claude application (Cmd + Q). MCP tools cannot be hot-reloaded into an ongoing conversation.

BaseLinker MCP Proxy & Catalog Management

@deerdesign/deertools includes a built-in, local BaseLinker MCP Proxy & Hub providing deep catalog management:

1. Product Catalog & Variations:
   • bl_catalog_get_product: Detailed product data with descriptions, features, channel-specific media, bundles and relations.
   • bl_catalog_create_or_update_product: Create or update products with SKU, EAN, tax rate, dimensions, weight, manufacturer, category.
   • bl_catalog_search_products: Filter products by name, SKU, EAN, category, or manufacturer.
2. Relationships & Cross-Selling:
   • bl_catalog_set_relations: Build product relationships (related, substitution, upsell, downsell, crosssell).
3. Product Features & Custom Text Fields:
   • bl_catalog_set_descriptions_and_features: Update descriptions and key-value parameter maps (features) per language.
4. Media & Image Galleries:
   • bl_catalog_manage_images: Add image URLs / base64 on positions 0–15, replace photos, or clear positions.
5. Categories, Manufacturers & Tags:
   • bl_catalog_categories, bl_catalog_manufacturers, bl_catalog_tags: Full CRUD for organizational taxonomies.
6. Bulk Price & Stock Updates:
   • bl_catalog_update_prices_batch & bl_catalog_update_stock_batch: Bulk updates up to 1000 items per call.
7. Rate Limiting & Safety:
   • Built-in token bucket rate-limiter prevents hitting BaseLinker's 100 req/min limit.
8. Live Web Dashboard:
   • Run deertools baselinker serve to open the local web UI at http://localhost:3456 with token tester and real-time agent audit stream.

DeerSkills Hub & MCP Ecosystem

DeerSkills Hub (https://skills.deergroup.pl) is the central platform for distributing, versioning, and managing AI Agent Skills and MCP servers across the Deer Design ecosystem:

1. Three-Tier Scope & Permission Model:
   • Company-Wide Official Skills (global): Verified organization-wide tools, visible to all employees, installed by default during agent initialization.
   • Team-Scoped Skills (team): Dedicated to specific functional teams (e.g., Architects, Sales Advisors, Estimators, Logistics, IT-Dev). Visible and installable strictly by members of that team. Teams and roles are fully configurable via deertools team and the web portal.
   • User Private Skills (user): Every employee can publish in their personal namespace @username/skill-slug. These remain 100% private until the author explicitly shares them with their team (deertools skill share --team <slug>) or submits them for global promotion (deertools skill promote).
2. Automated Secret Scanner:
   • Every deertools skill push runs a comprehensive regex scanner for live tokens and API keys (deer_*_live_, ghp_, sk-, X-BLToken, passwords).
   • Any unredacted secrets trigger an immediate safety halt with specific line citations, preventing credential leakage before upload.
3. SemVer Versioning & Visual Diff:
   • All revisions follow Semantic Versioning (1.0.0 -> 1.0.1 -> 1.1.0).
   • The web portal features an interactive side-by-side visual diff comparing file trees and SKILL.md content between releases.
   • CLI supports --bump patch|minor|major or explicit version flags.
4. Dependency Tracking (.deertools-lock.json):
   • Installed skills are tracked locally in .deertools-lock.json with SHA-256 integrity checksums and installed timestamps.
   • deertools doctor and deertools skill check detect outdated skills and prompt for automated updates.
5. Promotion Pipeline ("Nominate to Global"):
   • Authors can promote individual or team skills to the official company catalog via deertools skill promote <slug>.
   • Administrators review peer requests in the management dashboard and approve with one click.
6. AI Agent Tooling Integration (Cursor / Antigravity / Claude):
   • DeerSkills Hub exposes a dedicated Remote MCP server (https://skills.deergroup.pl/functions/v1/skills-mcp) compliant with the MCP 2024-11-05 standard.
   • Tools include: hub_search_skills, hub_get_skill, hub_publish_skill_version, hub_list_mcp_servers, hub_get_ecosystem_products.

Headless & CI/CD Environments

In CI pipelines or containerized agents where browser interaction is unavailable, provide API keys via environment variables:

export DEERTOOLS_CATALOG_KEY="deer_catalog_live_..."       # or DEERTOOLS_KATALOG_KEY
export DEERTOOLS_ESTIMATE_KEY="deer_kosztorys_live_..."    # or DEERTOOLS_KOSZTORYS_KEY
export DEERTOOLS_DELIVERIES_KEY="deer_dostawy_live_..."    # or DEERTOOLS_DOSTAWY_KEY
export DEERTOOLS_SUPPLIER_KEY="deer_supplier_live_..."
export DEERTOOLS_RENDERMIND_KEY="deer_rendermind_live_..."

# Custom credentials directory:
export DEERTOOLS_HOME="/custom/path/.deertools"

Exit Codes

Development & Testing

DeerTools CLI is written in pure, dependency-free modern Node.js using built-in modules (node:crypto, node:http, node:fs, node:test).

# Run test suite:
npm test

License

MIT © Deer Design AI Team