Skip to content

README.md

Latest commit

 

History

History
108 lines (85 loc) · 4.48 KB

README.md

File metadata and controls

108 lines (85 loc) · 4.48 KB
Raw

Attio CLI Documentation

This directory contains comprehensive documentation for the Attio CLI project, covering API concepts, endpoints, CLI specifications, and implementation plan.

Documentation Index

Core Concepts & API Fundamentals

  1. Core Concepts - Objects, records, lists, attributes, workspaces, actors, slugs vs IDs
  2. Authentication - API keys, OAuth, scopes, environment configuration
  3. API Fundamentals - Base URL, rate limiting, pagination, filtering, sorting, error handling

API Endpoints Reference

Configuration & Metadata

  1. Workspaces & Members - Workspace member management
  2. Objects & Attributes - Object definitions, attribute management, select/status options

Records (Standard Objects)

  1. Records (Generic) - Generic record operations (list, get, create, update, assert, delete)
  2. People Records - People-specific endpoints and attributes
  3. Company Records - Company-specific endpoints and attributes
  4. Deal Records - Deal-specific endpoints and attributes

Lists & Workflows

  1. Lists & Entries - List management, entry operations, assert entries, multiselect handling

Content & Activities

  1. Notes - Create, read, update, delete notes with markdown support
  2. Tasks - Task management, assignment, filtering
  3. Meetings - Meeting queries, participant filtering (read-only)

CLI Design & Implementation

  1. CLI Specification - Complete CLI command structure, arguments, options, examples
  2. Implementation Plan - Phase-by-phase development plan with test specifications

Quick Reference

Standard Objects

  • people: Individual contacts with emails, phone numbers, social profiles
  • companies: Organizations with domains, employee counts, categories
  • deals: Sales opportunities with stages, values, owners
  • users: Workspace user records
  • workspaces: Workspace records

Key API Patterns

Creating Records

POST /v2/objects/{object}/records
PUT /v2/objects/{object}/records?matching_attribute=email_addresses  # Assert

Working with Lists

GET /v2/lists                                    # List all lists
POST /v2/lists/{list}/entries                    # Add record to list
PUT /v2/lists/{list}/entries                     # Assert entry
PATCH /v2/lists/{list}/entries/{entry_id}        # Update (append multiselect)

Filtering & Querying

POST /v2/objects/people/records/query
# Body: {"filter": {"email_addresses": {"$contains": "@example.com"}}}

CLI Commands Structure

attio <resource> <action> [arguments] [options]

# Examples:
attio workspace members list
attio record create people --data '{...}'
attio entry list my_list --filter '{...}'
attio note create --parent-object people --parent-record-id abc-123
attio task list --linked-object people --completed false

Implementation Phases

  1. Phase 0: Project setup (TypeScript, testing, dependencies)
  2. Phase 1: API client foundation (HTTP client, auth, errors)
  3. Phase 2: Type definitions & validation (Zod schemas)
  4. Phase 3: Workspace endpoints & CLI
  5. Phase 4: Objects & attributes
  6. Phase 5: Records (people, companies, deals)
  7. Phase 6: Lists & entries
  8. Phase 7: Notes
  9. Phase 7a: Tasks
  10. Phase 7b: Meetings
  11. Phase 8: Output formatting & polish
  12. Phase 9: Integration testing & documentation
  13. Phase 10: Build & distribution

Type Safety Requirements

  • TypeScript strict mode: No implicit any, strict null checks
  • No null/undefined: Use explicit error throwing for missing values
  • Runtime validation: Zod schemas for all API responses
  • Branded types: UUIDs and slugs have distinct types

Development Principles

  • Test-Driven Development: Write tests before implementation
  • No premature optimization: Implement minimal working solutions
  • Explicit error handling: Clear, user-friendly error messages
  • Agent-friendly design: Predictable JSON output, clear exit codes
  • Comprehensive help: Every command has examples and documentation