@wavyx/pdcli 0.1.0

package/src/commands/deal/list.js

@@ -0,0 +1,62 @@
+import { Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { collectPages } from '../../lib/pagination.js'
+
+const columns = {
+  id: { header: 'ID' },
+  title: { header: 'Title' },
+  value: {
+    header: 'Value',
+    get: (row) =>
+      row.value != null ? `${row.value} ${row.currency ?? ''}`.trim() : '',
+  },
+  status: { header: 'Status' },
+  stage_id: { header: 'Stage' },
+  person_id: { header: 'Person' },
+  org_id: { header: 'Org' },
+  owner_id: { header: 'Owner' },
+}
+
+export default class DealListCommand extends BaseCommand {
+  static description = 'List deals'
+
+  static examples = [
+    '<%= config.bin %> deal list',
+    '<%= config.bin %> deal list --status won --limit 50',
+    '<%= config.bin %> deal list --stage 3 --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    status: Flags.string({
+      description: 'Filter by status',
+      options: ['open', 'won', 'lost', 'deleted'],
+    }),
+    stage: Flags.integer({ description: 'Filter by stage ID' }),
+    pipeline: Flags.integer({ description: 'Filter by pipeline ID' }),
+    owner: Flags.integer({ description: 'Filter by owner (user) ID' }),
+    person: Flags.integer({ description: 'Filter by person ID' }),
+    org: Flags.integer({ description: 'Filter by organization ID' }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(DealListCommand)
+    const limit = flags.limit ?? 100
+
+    const query = {
+      status: flags.status,
+      stage_id: flags.stage,
+      pipeline_id: flags.pipeline,
+      owner_id: flags.owner,
+      person_id: flags.person,
+      org_id: flags.org,
+      limit: Math.min(limit, 100),
+    }
+
+    const items = await collectPages(
+      this.apiClient.pageV2('/api/v2/deals', query),
+      limit,
+    )
+    await this.outputResults(items, columns)
+  }
+}

package/src/commands/doctor.js

@@ -0,0 +1,123 @@
+import chalk from 'chalk'
+import ora from 'ora'
+import BaseCommand from '../base-command.js'
+import { getConf, getActiveProfile, getProfileConfig } from '../lib/config.js'
+import { getToken, isKeychainAvailable } from '../lib/keychain.js'
+import { companyDomainToBaseOrigin } from '../lib/auth.js'
+
+const PASS = chalk.green('✔')
+const FAIL = chalk.red('✘')
+
+export default class DoctorCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'Run diagnostic checks on the CLI environment'
+
+  static examples = ['<%= config.bin %> doctor']
+
+  async run() {
+    const spinner = ora('Running diagnostics...').start()
+    const results = []
+
+    // 1. Config directory accessible
+    try {
+      getConf()
+      results.push({ label: 'Config directory accessible', ok: true })
+    } catch {
+      results.push({
+        label: 'Config directory accessible',
+        ok: false,
+        detail: 'Cannot access config store',
+      })
+    }
+
+    // 2. Keychain available
+    const keychainOk = isKeychainAvailable()
+    results.push({
+      label: 'Keychain available',
+      ok: keychainOk,
+      detail: keychainOk
+        ? undefined
+        : 'OS keychain unavailable; pdcli cannot store credentials',
+    })
+
+    // 3. Active profile set
+    let profile
+    try {
+      profile = getActiveProfile()
+      results.push({ label: 'Active profile set', ok: true, detail: profile })
+    } catch {
+      results.push({ label: 'Active profile set', ok: false })
+    }
+
+    // 4. Company domain set
+    const domain = profile
+      ? getProfileConfig(profile, 'company_domain')
+      : undefined
+    results.push({
+      label: 'Company domain set',
+      ok: Boolean(domain),
+      detail: domain ?? 'Run: pdcli auth login',
+    })
+
+    // 5. Token present
+    if (profile) {
+      const token = await getToken(profile)
+      results.push({
+        label: 'API token present',
+        ok: token !== null,
+        detail: token ? undefined : 'Run: pdcli auth login',
+      })
+    } else {
+      results.push({
+        label: 'API token present',
+        ok: false,
+        detail: 'No active profile',
+      })
+    }
+
+    // 6. API reachable (any HTTP response from the company host counts —
+    //    a 401 still proves the host resolves and answers)
+    if (domain) {
+      try {
+        await fetch(`${companyDomainToBaseOrigin(domain)}/api/v1/users/me`, {
+          signal: AbortSignal.timeout(5000),
+        })
+        results.push({ label: 'API reachable', ok: true })
+      } catch {
+        results.push({
+          label: 'API reachable',
+          ok: false,
+          detail: `Could not reach ${domain}.pipedrive.com`,
+        })
+      }
+    } else {
+      results.push({
+        label: 'API reachable',
+        ok: false,
+        detail: 'No company domain configured',
+      })
+    }
+
+    spinner.stop()
+
+    this.log('')
+    this.log(chalk.bold('Pipedrive CLI Diagnostics'))
+    this.log('')
+
+    for (const { label, ok, detail } of results) {
+      const icon = ok ? PASS : FAIL
+      const suffix = detail ? chalk.dim(` (${detail})`) : ''
+      this.log(`  ${icon} ${label}${suffix}`)
+    }
+
+    this.log('')
+
+    const failed = results.filter((r) => !r.ok).length
+    if (failed > 0) {
+      this.log(chalk.yellow(`${failed} check${failed > 1 ? 's' : ''} failed`))
+    } else {
+      this.log(chalk.green('All checks passed'))
+    }
+  }
+}

package/src/commands/field/get.js

@@ -0,0 +1,58 @@
+import { Args } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { getFields, makeResolver } from '../../lib/fields.js'
+import { CliError } from '../../lib/errors.js'
+
+export default class FieldGetCommand extends BaseCommand {
+  static description = 'Show one field by human name or hashed key'
+
+  static examples = [
+    '<%= config.bin %> field get deal "Deal Size"',
+    '<%= config.bin %> field get deal dcf558aac1ae4e8c4f849ba5e668430d8df9be12',
+  ]
+
+  static args = {
+    entity: Args.string({
+      required: true,
+      description: 'Entity type',
+      options: ['deal', 'person', 'org', 'organization', 'product', 'activity'],
+    }),
+    field: Args.string({
+      required: true,
+      description: 'Field name (human label) or hashed key',
+    }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  async run() {
+    const { args } = await this.parse(FieldGetCommand)
+
+    const defs = await getFields(this.apiClient, args.entity)
+    const resolver = makeResolver(defs)
+
+    const key = resolver.nameToKey(args.field) ?? args.field
+    const def = defs.find((d) => d.field_code === key)
+
+    if (!def) {
+      throw new CliError(
+        `No field named or keyed "${args.field}" on ${args.entity}. ` +
+          `Run: pdcli field list ${args.entity}`,
+        { exitCode: 65 },
+      )
+    }
+
+    await this.outputResults(def, {
+      field_code: { header: 'Key' },
+      field_name: { header: 'Name' },
+      field_type: { header: 'Type' },
+      options: {
+        header: 'Options',
+        get: (row) =>
+          row.options?.map((o) => `${o.id}=${o.label}`).join(', ') ?? '',
+      },
+    })
+  }
+}

package/src/commands/field/list.js

@@ -0,0 +1,41 @@
+import { Args } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { getFields } from '../../lib/fields.js'
+
+export default class FieldListCommand extends BaseCommand {
+  static description =
+    'List fields for an entity, including custom-field hash keys'
+
+  static examples = [
+    '<%= config.bin %> field list deal',
+    '<%= config.bin %> field list person --output json',
+  ]
+
+  static args = {
+    entity: Args.string({
+      required: true,
+      description: 'Entity type',
+      options: ['deal', 'person', 'org', 'organization', 'product', 'activity'],
+    }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  async run() {
+    const { args } = await this.parse(FieldListCommand)
+
+    const defs = await getFields(this.apiClient, args.entity)
+
+    await this.outputResults(defs, {
+      field_code: { header: 'Key' },
+      field_name: { header: 'Name' },
+      field_type: { header: 'Type' },
+      options: {
+        header: 'Options',
+        get: (row) => row.options?.map((o) => o.label).join(', ') ?? '',
+      },
+    })
+  }
+}

package/src/commands/org/get.js

@@ -0,0 +1,41 @@
+import { Args } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { getFields, makeResolver } from '../../lib/fields.js'
+import { flattenRecord } from '../../lib/output/record.js'
+
+export default class OrgGetCommand extends BaseCommand {
+  static description = 'Get an organization by ID'
+
+  static examples = [
+    '<%= config.bin %> org get 7',
+    '<%= config.bin %> org get 7 --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Organization ID' }),
+  }
+
+  async run() {
+    const { args } = await this.parse(OrgGetCommand)
+    const body = await this.apiClient.get(`/api/v2/organizations/${args.id}`)
+    let record = body.data
+
+    if (this.resolveFormat() === 'table') {
+      if (record.custom_fields && Object.keys(record.custom_fields).length) {
+        const defs = await getFields(this.apiClient, 'org')
+        record = makeResolver(defs).resolveCustomFields(record)
+      }
+      await this.outputResults(flattenRecord(record), {
+        field: { header: 'Field' },
+        value: { header: 'Value' },
+      })
+      return
+    }
+
+    await this.outputResults(record, {})
+  }
+}

package/src/commands/org/list.js

@@ -0,0 +1,40 @@
+import { Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { collectPages } from '../../lib/pagination.js'
+
+const columns = {
+  id: { header: 'ID' },
+  name: { header: 'Name' },
+  owner_id: { header: 'Owner' },
+  add_time: { header: 'Created' },
+}
+
+export default class OrgListCommand extends BaseCommand {
+  static description = 'List organizations'
+
+  static examples = [
+    '<%= config.bin %> org list',
+    '<%= config.bin %> org list --owner 3 --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    owner: Flags.integer({ description: 'Filter by owner (user) ID' }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(OrgListCommand)
+    const limit = flags.limit ?? 100
+
+    const query = {
+      owner_id: flags.owner,
+      limit: Math.min(limit, 100),
+    }
+
+    const items = await collectPages(
+      this.apiClient.pageV2('/api/v2/organizations', query),
+      limit,
+    )
+    await this.outputResults(items, columns)
+  }
+}

package/src/commands/person/get.js

@@ -0,0 +1,41 @@
+import { Args } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { getFields, makeResolver } from '../../lib/fields.js'
+import { flattenRecord } from '../../lib/output/record.js'
+
+export default class PersonGetCommand extends BaseCommand {
+  static description = 'Get a person by ID'
+
+  static examples = [
+    '<%= config.bin %> person get 5',
+    '<%= config.bin %> person get 5 --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  static args = {
+    id: Args.integer({ required: true, description: 'Person ID' }),
+  }
+
+  async run() {
+    const { args } = await this.parse(PersonGetCommand)
+    const body = await this.apiClient.get(`/api/v2/persons/${args.id}`)
+    let record = body.data
+
+    if (this.resolveFormat() === 'table') {
+      if (record.custom_fields && Object.keys(record.custom_fields).length) {
+        const defs = await getFields(this.apiClient, 'person')
+        record = makeResolver(defs).resolveCustomFields(record)
+      }
+      await this.outputResults(flattenRecord(record), {
+        field: { header: 'Field' },
+        value: { header: 'Value' },
+      })
+      return
+    }
+
+    await this.outputResults(record, {})
+  }
+}

package/src/commands/person/list.js

@@ -0,0 +1,49 @@
+import { Flags } from '@oclif/core'
+import BaseCommand from '../../base-command.js'
+import { collectPages } from '../../lib/pagination.js'
+
+function primary(list) {
+  if (!Array.isArray(list) || list.length === 0) return ''
+  return (list.find((e) => e.primary) ?? list[0]).value ?? ''
+}
+
+const columns = {
+  id: { header: 'ID' },
+  name: { header: 'Name' },
+  email: { header: 'Email', get: (row) => primary(row.emails) },
+  phone: { header: 'Phone', get: (row) => primary(row.phones) },
+  org_id: { header: 'Org' },
+  owner_id: { header: 'Owner' },
+}
+
+export default class PersonListCommand extends BaseCommand {
+  static description = 'List persons (contacts)'
+
+  static examples = [
+    '<%= config.bin %> person list',
+    '<%= config.bin %> person list --org 7 --output json',
+  ]
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    owner: Flags.integer({ description: 'Filter by owner (user) ID' }),
+    org: Flags.integer({ description: 'Filter by organization ID' }),
+  }
+
+  async run() {
+    const { flags } = await this.parse(PersonListCommand)
+    const limit = flags.limit ?? 100
+
+    const query = {
+      owner_id: flags.owner,
+      org_id: flags.org,
+      limit: Math.min(limit, 100),
+    }
+
+    const items = await collectPages(
+      this.apiClient.pageV2('/api/v2/persons', query),
+      limit,
+    )
+    await this.outputResults(items, columns)
+  }
+}

package/src/commands/profile/current.js

@@ -0,0 +1,16 @@
+import chalk from 'chalk'
+import BaseCommand from '../../base-command.js'
+import { getActiveProfile } from '../../lib/config.js'
+
+export default class ProfileCurrentCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'Show the active profile'
+
+  static examples = ['<%= config.bin %> profile current']
+
+  async run() {
+    const active = getActiveProfile()
+    this.log(chalk.cyan(active))
+  }
+}

package/src/commands/profile/list.js

@@ -0,0 +1,36 @@
+import chalk from 'chalk'
+import BaseCommand from '../../base-command.js'
+import { getAllProfiles, getActiveProfile } from '../../lib/config.js'
+import { getToken } from '../../lib/keychain.js'
+
+export default class ProfileListCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'List all configured profiles'
+
+  static examples = ['<%= config.bin %> profile list']
+
+  async run() {
+    const profiles = getAllProfiles()
+    const active = getActiveProfile()
+    const names = new Set(Object.keys(profiles))
+
+    const activeToken = await getToken(active)
+    if (activeToken) names.add(active)
+
+    if (names.size === 0) {
+      this.log('No profiles configured. Run: pdcli auth login')
+      return
+    }
+
+    for (const name of names) {
+      const token = await getToken(name)
+      const status = token ? chalk.dim(' (authenticated)') : ''
+      if (name === active) {
+        this.log(chalk.green(`* ${name}`) + status)
+      } else {
+        this.log(`  ${name}${status}`)
+      }
+    }
+  }
+}

package/src/commands/profile/use.js

@@ -0,0 +1,26 @@
+import { Args } from '@oclif/core'
+import chalk from 'chalk'
+import BaseCommand from '../../base-command.js'
+import { setActiveProfile } from '../../lib/config.js'
+
+export default class ProfileUseCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'Switch the active profile'
+
+  static examples = ['<%= config.bin %> profile use work']
+
+  static args = {
+    name: Args.string({
+      required: true,
+      description: 'Profile name to activate',
+    }),
+  }
+
+  async run() {
+    const { args } = await this.parse(ProfileUseCommand)
+
+    setActiveProfile(args.name)
+    this.log(`Switched to profile ${chalk.cyan(args.name)}`)
+  }
+}

package/src/commands/search.js

@@ -0,0 +1,67 @@
+import { Args, Flags } from '@oclif/core'
+import BaseCommand from '../base-command.js'
+import { CliError } from '../lib/errors.js'
+
+const columns = {
+  type: { header: 'Type' },
+  id: { header: 'ID' },
+  name: {
+    header: 'Name / Title',
+    get: (row) => row.title ?? row.name ?? '',
+  },
+}
+
+export default class SearchCommand extends BaseCommand {
+  static description =
+    'Search across deals, persons, organizations, products, leads, files, and projects'
+
+  static examples = [
+    '<%= config.bin %> search "acme"',
+    '<%= config.bin %> search "acme" --item-types deal,person --output json',
+  ]
+
+  static args = {
+    term: Args.string({ required: true, description: 'Search term' }),
+  }
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    'item-types': Flags.string({
+      description:
+        'Comma-separated item types (deal,person,organization,product,lead,file,mail_attachment,project)',
+    }),
+    exact: Flags.boolean({
+      description: 'Exact match (allows 1-character terms)',
+      default: false,
+    }),
+  }
+
+  async run() {
+    const { args, flags } = await this.parse(SearchCommand)
+
+    const minLength = flags.exact ? 1 : 2
+    if (args.term.length < minLength) {
+      throw new CliError(
+        `Search term must be at least 2 characters (1 with --exact)`,
+        { exitCode: 64 },
+      )
+    }
+
+    // Search costs 40 rate-limit tokens — single request, no auto-paging.
+    const body = await this.apiClient.get('/api/v2/itemSearch', {
+      query: {
+        term: args.term,
+        item_types: flags['item-types'],
+        exact_match: flags.exact ? true : undefined,
+        limit: flags.limit,
+      },
+    })
+
+    const items = (body.data?.items ?? []).map((entry) => ({
+      ...entry.item,
+      result_score: entry.result_score,
+    }))
+
+    await this.outputResults(items, columns)
+  }
+}

package/src/commands/user/me.js

@@ -0,0 +1,26 @@
+import BaseCommand from '../../base-command.js'
+
+export default class UserMeCommand extends BaseCommand {
+  static description = 'Show the authenticated user'
+
+  static examples = ['<%= config.bin %> user me']
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+  }
+
+  async run() {
+    await this.parse(UserMeCommand)
+
+    // Users API is v1-only (no v2 equivalent as of June 2026).
+    const body = await this.apiClient.get('/api/v1/users/me')
+
+    await this.outputResults(body.data, {
+      id: { header: 'ID' },
+      name: { header: 'Name' },
+      email: { header: 'Email' },
+      is_admin: { header: 'Admin' },
+      timezone_name: { header: 'Timezone' },
+    })
+  }
+}

package/src/commands/version.js

@@ -0,0 +1,24 @@
+import chalk from 'chalk'
+import BaseCommand from '../base-command.js'
+import { getProfileConfig } from '../lib/config.js'
+import { companyDomainToBaseOrigin } from '../lib/auth.js'
+
+export default class VersionCommand extends BaseCommand {
+  static skipAuth = true
+
+  static description = 'Show CLI version and environment info'
+
+  static examples = ['<%= config.bin %> version']
+
+  async run() {
+    const domain = getProfileConfig(this.activeProfile, 'company_domain')
+    const apiBase = domain
+      ? companyDomainToBaseOrigin(domain)
+      : chalk.dim('(not set)')
+
+    this.log(`${chalk.bold('pdcli')} ${chalk.cyan(this.config.version)}`)
+    this.log(`Node:     ${process.version}`)
+    this.log(`API base: ${apiBase}`)
+    this.log(`Platform: ${process.platform}-${process.arch}`)
+  }
+}

package/src/hooks/command-not-found.js

@@ -0,0 +1,15 @@
+import createDebug from 'debug'
+import chalk from 'chalk'
+
+const debug = createDebug('pd:command-not-found')
+
+export default async function commandNotFound(options) {
+  debug('command not found: %s', options.id)
+  process.stderr.write(
+    `${chalk.red('Error:')} ${chalk.yellow(options.id)} is not a pdcli command.\n`,
+  )
+  process.stderr.write(
+    `Run ${chalk.cyan('pdcli help')} for a list of available commands.\n`,
+  )
+  process.exit(127)
+}

package/src/hooks/init.js

@@ -0,0 +1,7 @@
+import createDebug from 'debug'
+
+const debug = createDebug('pd:init')
+
+export default async function init() {
+  debug('pdcli init hook')
+}