NOTICKET Add adjustable output format per subcommand (#3)

* Add adjustable output format option per subcommand

Adds --format / -f flag to all 11 subcommands with choices: json (default), jsonl, csv, yaml, table. Nested objects are stringified for csv/table formats. Adds js-yaml dependency for YAML serialization.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Fix output format edge cases from code review

- Validate --format input; exit with error on unknown value
- Derive CSV/table headers from union of all row keys, not just rows[0]
- Replace Math.max(...array) spread with reduce to avoid call stack limit
- Fix CSV escaping: escape headers, handle \r, use \r\n line endings (RFC 4180)
- Remove dead default parameter from print() since Commander always passes the value
- Fix companies search: --industry no longer silently overwrites --query
- Add comment clarifying YAML intentionally skips toRows() to preserve full structure
- Add comment explaining FORMAT_OPTION tuple positional contract

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Document --format option in README and apollo-cli skill

Adds a "Output formats" section covering json/jsonl/csv/yaml/table,
when to use each, and the nested-response caveat for csv/table.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: brandonapollo

.claude/skills/apollo-cli/SKILL.md

@@ -6,7 +6,7 @@ version: 1.0.0
 
 # Apollo CLI Skill
 
-Use the `apollo` CLI to search and enrich people and companies, find job postings, and surface news from Apollo.io. All output is JSON — pipe with `jq` to extract specific fields.
+Use the `apollo` CLI to search and enrich people and companies, find job postings, and surface news from Apollo.io. Output defaults to JSON for `jq` piping; use `-f, --format` to switch to `jsonl`, `csv`, `yaml`, or `table`.
 
 ## Authentication
 
@@ -114,9 +114,29 @@ apollo news search --id <organization_id>
 
 ---
 
+## Output formats
+
+Every subcommand accepts `-f, --format <format>`:
+
+| Format | When to use |
+|---|---|
+| `json` (default) | Pretty-printed JSON. Pipe to `jq` for field extraction. |
+| `jsonl` | One JSON object per line. Stream into log/data pipelines. |
+| `csv` | Flat CSV with headers; nested objects/arrays are stringified. Open in spreadsheets or feed to `mlr`/`csvkit`. |
+| `yaml` | Human-readable YAML. Good for inspecting deeply nested responses. |
+| `table` | ASCII bordered table. Good for terminal browsing of small responses. |
+
+```bash
+apollo companies search --industry saas --format table
+apollo people bulk-enrich --emails a@b.com c@d.com --format jsonl
+apollo news search --company Stripe --format yaml
+```
+
+For nested responses (search/list endpoints with pagination + items), prefer `json` + `jq` or `yaml`. `csv`/`table` will stringify nested structures into a single cell.
+
 ## Piping with jq
 
-All commands output JSON. Use `jq` to extract specific fields:
+For default JSON output, use `jq` to extract specific fields:
 
 ```bash
 # Names and titles of VPs at Stripe

README.md

@@ -1,6 +1,6 @@
 # apollo-io-cli
 
-A command-line interface for the [Apollo.io API](https://apolloio.github.io/apollo-api-docs/). Search and enrich people and companies, find job postings, and surface news — all from your terminal, pipeable with `jq`.
+A command-line interface for the [Apollo.io API](https://apolloio.github.io/apollo-api-docs/). Search and enrich people and companies, find job postings, and surface news — all from your terminal, pipeable with `jq` and switchable to CSV / YAML / JSONL / table output.
 
 <img width="1908" height="2294" alt="image" src="https://github.com/user-attachments/assets/eb7ebc43-1c64-466d-8959-e9c6e185433a" />
 
@@ -218,9 +218,34 @@ For agents not using Claude Code, see [`AGENTS.md`](./AGENTS.md) at the root for
 
 ---
 
+## Output formats
+
+Every subcommand accepts `-f, --format <format>` (default `json`):
+
+| Format | Description |
+|---|---|
+| `json` | Pretty-printed JSON. Default. Pipe to `jq` for field extraction. |
+| `jsonl` | One JSON object per line. Useful for streaming into log/data pipelines. |
+| `csv` | Flat CSV with headers; nested objects/arrays are stringified into a single cell. |
+| `yaml` | Human-readable YAML. Easier to scan for deeply nested responses. |
+| `table` | ASCII bordered table. Good for quick terminal browsing of small responses. |
+
+```bash
+apollo companies search --industry saas --format table
+apollo people bulk-enrich --emails a@b.com c@d.com --format jsonl
+apollo news search --company "Stripe" --format yaml
+apollo people search --title "CTO" --domain stripe.com --format csv > ctos.csv
+```
+
+> Search/list responses include both pagination metadata and an array of records. `csv` and `table` formats render these as two columns with the array stringified — for analysis, prefer `json` + `jq` to project just the records:
+>
+> ```bash
+> apollo companies search --industry saas --format json | jq '.organizations[]' --compact-output > orgs.jsonl
+> ```
+
 ## Piping with jq
 
-All commands output JSON to stdout, making them composable with `jq`:
+Default JSON output is composable with `jq`:
 
 ```bash
 # Get names and titles of VP Engineering at Stripe

bun.lock

@@ -12,6 +12,7 @@
     "build:all": "bun build ./src/index.js --compile --target=bun-darwin-arm64 --outfile dist/apollo-macos-arm64 && bun build ./src/index.js --compile --target=bun-darwin-x64 --outfile dist/apollo-macos-x64 && bun build ./src/index.js --compile --target=bun-linux-x64 --outfile dist/apollo-linux-x64"
   },
   "dependencies": {
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.1"
   }
 }

package.json

@@ -1,5 +1,5 @@
 import { apolloGet, apolloRequest } from '../api.js';
-import { print } from '../output.js';
+import { print, FORMAT_OPTION } from '../output.js';
 import { parsePageOptions } from '../utils.js';
 
 export function registerCompanies(program) {
@@ -20,14 +20,15 @@ export function registerCompanies(program) {
     .option('--hiring-for <titles...>', 'Currently hiring for job title(s)')
     .option('--per-page <n>', 'Results per page', '10')
     .option('--page <n>', 'Page number', '1')
+    .option(...FORMAT_OPTION)
     .action(async (opts) => {
       const body = parsePageOptions(opts);
 
-      if (opts.query) body.q_organization_keyword_tags = [opts.query];
+      if (opts.industry) body.q_organization_keyword_tags = opts.industry;
+      else if (opts.query) body.q_organization_keyword_tags = [opts.query];
       if (opts.location) body.organization_locations = opts.location;
       if (opts.notLocation) body.organization_not_locations = opts.notLocation;
       if (opts.employees) body.organization_num_employees_ranges = [opts.employees];
-      if (opts.industry) body.q_organization_keyword_tags = opts.industry;
       if (opts.technology) body.currently_using_any_of_technology_uids = opts.technology;
       if (opts.revenue) {
         const [min, max] = opts.revenue.split(',');
@@ -44,14 +45,15 @@ export function registerCompanies(program) {
       if (opts.hiringFor) body.q_organization_job_titles = opts.hiringFor;
 
       const data = await apolloRequest('/mixed_companies/search', body);
-      print(data);
+      print(data, opts.format);
     });
 
   companies
     .command('enrich')
     .description('Enrich a company profile')
     .option('--domain <domain>', 'Company domain (e.g. acme.com)')
     .option('--name <name>', 'Company name')
+    .option(...FORMAT_OPTION)
     .action(async (opts) => {
       if (!opts.domain && !opts.name) {
         console.error('Error: provide --domain or --name');
@@ -75,7 +77,7 @@ export function registerCompanies(program) {
           process.exit(1);
         }
         const data = await apolloRequest('/organizations/enrich', { domain });
-        print(data);
+        print(data, opts.format);
         return;
       }
 
@@ -84,30 +86,32 @@ export function registerCompanies(program) {
       if (opts.name) body.name = opts.name;
 
       const data = await apolloRequest('/organizations/enrich', body);
-      print(data);
+      print(data, opts.format);
     });
 
   companies
     .command('bulk-enrich')
     .description('Enrich multiple companies by domain')
     .requiredOption('--domains <domains...>', 'Company domains to enrich')
+    .option(...FORMAT_OPTION)
     .action(async (opts) => {
       const body = { domains: opts.domains };
       const data = await apolloRequest('/organizations/bulk_enrich', body);
-      print(data);
+      print(data, opts.format);
     });
 
   companies
     .command('get')
     .description('Get full details for a company by ID')
     .requiredOption('--id <id>', 'Apollo organization ID')
+    .option(...FORMAT_OPTION)
     .action(async (opts) => {
       const data = await apolloRequest('/mixed_companies/search', {
         organization_ids: [opts.id],
         per_page: 1,
         page: 1,
       });
-      print(data);
+      print(data, opts.format);
     });
 
   companies
@@ -116,9 +120,10 @@ export function registerCompanies(program) {
     .requiredOption('--id <id>', 'Apollo organization ID')
     .option('--per-page <n>', 'Results per page', '10')
     .option('--page <n>', 'Page number', '1')
+    .option(...FORMAT_OPTION)
     .action(async (opts) => {
       const { page, per_page } = parsePageOptions(opts);
       const data = await apolloGet(`/organizations/${opts.id}/job_postings`, { page, per_page });
-      print(data);
+      print(data, opts.format);
     });
 }

src/commands/companies.js

@@ -1,5 +1,5 @@
 import { apolloRequest } from '../api.js';
-import { print } from '../output.js';
+import { print, FORMAT_OPTION } from '../output.js';
 import { parsePageOptions } from '../utils.js';
 
 export function registerNews(program) {
@@ -12,6 +12,7 @@ export function registerNews(program) {
     .option('--id <id>', 'Apollo organization ID to filter by')
     .option('--per-page <n>', 'Results per page', '10')
     .option('--page <n>', 'Page number', '1')
+    .option(...FORMAT_OPTION)
     .action(async (opts) => {
       if (!opts.company && !opts.id) {
         console.error('Error: provide --company or --id');
@@ -39,6 +40,6 @@ export function registerNews(program) {
         page,
         per_page,
       });
-      print(data);
+      print(data, opts.format);
     });
 }

src/commands/news.js

@@ -1,5 +1,5 @@
 import { apolloGet, apolloRequest } from '../api.js';
-import { print } from '../output.js';
+import { print, FORMAT_OPTION } from '../output.js';
 import { parsePageOptions } from '../utils.js';
 
 export function registerPeople(program) {
@@ -18,6 +18,7 @@ export function registerPeople(program) {
     .option('--industry <industries...>', 'Industry(s) to filter by')
     .option('--per-page <n>', 'Results per page', '10')
     .option('--page <n>', 'Page number', '1')
+    .option(...FORMAT_OPTION)
     .action(async (opts) => {
       const body = parsePageOptions(opts);
 
@@ -31,7 +32,7 @@ export function registerPeople(program) {
       if (opts.industry) body.organization_industry_tag_ids = opts.industry;
 
       const data = await apolloRequest('/mixed_people/api_search', body);
-      print(data);
+      print(data, opts.format);
     });
 
   people
@@ -43,6 +44,7 @@ export function registerPeople(program) {
     .option('--last-name <name>', 'Last name (use with --first-name and --company)')
     .option('--name <name>', 'Full name (use with --company)')
     .option('--company <domain>', 'Company domain (use with --name or --first-name/--last-name)')
+    .option(...FORMAT_OPTION)
     .action(async (opts) => {
       if (!opts.email && !opts.linkedin && !opts.firstName && !opts.name) {
         console.error('Error: provide --email, --linkedin, or --name/--first-name with --company');
@@ -58,26 +60,28 @@ export function registerPeople(program) {
       if (opts.company) body.organization_name = opts.company;
 
       const data = await apolloRequest('/people/match', body);
-      print(data);
+      print(data, opts.format);
     });
 
   people
     .command('bulk-enrich')
     .description('Enrich multiple people by email')
     .requiredOption('--emails <emails...>', 'Email addresses to enrich')
+    .option(...FORMAT_OPTION)
     .action(async (opts) => {
       const body = { details: opts.emails.map(email => ({ email })) };
       const data = await apolloRequest('/people/bulk_match', body);
-      print(data);
+      print(data, opts.format);
     });
 
   people
     .command('email')
     .description('Get the email address for a person by Apollo person ID')
     .requiredOption('--id <id>', 'Apollo person ID')
+    .option(...FORMAT_OPTION)
     .action(async (opts) => {
       const data = await apolloGet('/people/match', { id: opts.id });
-      print(data);
+      print(data, opts.format);
     });
 
   people
@@ -88,6 +92,7 @@ export function registerPeople(program) {
     .option('--linkedin <url>', 'Company LinkedIn URL')
     .option('--per-page <n>', 'Results per page', '10')
     .option('--page <n>', 'Page number', '1')
+    .option(...FORMAT_OPTION)
     .action(async (opts) => {
       const body = parsePageOptions(opts);
 
@@ -96,6 +101,6 @@ export function registerPeople(program) {
       if (opts.linkedin) body.organization_linkedin_url = opts.linkedin;
 
       const data = await apolloRequest('/mixed_people/api_search', body);
-      print(data);
+      print(data, opts.format);
     });
 }