cli: make apollo user-friendly

The apollo command is basically functional but so, so user unfriendly. It's user-hostile. Amti-user

It's not so much a problem right now because there's only one service on apollo and it barely works

This issue is a list of possible improvements that can be made.

Make it easy to get to my server's landing page

The Apollo server itself shows a rich html listing of what services are available, and provides the readme for each. We should make it easy to get the active server's help pages (local, staging or prod)

List available services

openfn apollo ls should list all the services, just like the apollo root soes

Show detailed docs for a service

openfn apollo help <service-name> should print detailed help, including usage examples, for a given endpoint.

The help data must come the apollo server. Does this mean we just dump the readme?

Generate sample data

Some services need sample data. Can the server provide one or more sample datasets and the CLI auto-download them? I'd like to run openfn apollo adator_gen with default values and get something back. I think? Is that even a nonsense use case?

Make API key management easier

Many services need API keys, and at the moment it's the wild west.

It would be nice to do:

openfn apollo add-key <model-name> <key>

And then whenever the CLI calls a service with that model, it can default api_key to that key.

I guess the key is saved, encrypted, in the CLI repo.

Read Env vars

In JSON payloads, we should be able to read stuff from env vars. Like any value of the form $API_KEY (all one word, all caps, start with dollar) we should try and resolve against process.env

We could also allow payloads to be a JS module that exports JSON, which gives better env management and even data generation capabilities.

Add utils or wrappers for template generation

Template generation is kinda hard.

• I need to get an openAPI spec
• Even worse, right now I need to download it to JSON and copy/paste it into my payload
• I need to work out what endpoints are available and enter the right one
• There is no integration to the monorepo so I can't easily raise a PR

Ideas:

• allow the spec json object to take a URL. Either the CLI or the remote service should be able to map this to JSON
• give me some openapi helper functions, like listing all the endpoints for a particular API. I don't think this is worth the effort to be fair
• There's a difference betwee generating adaptor.js and generating an adaptor. There's an extra chunk of logic in the CLI that needs to generate an adaptor template in the monorepo, generate adaptor.js, and paste the generated adaptor in the right place. I have been thinking of this as a bespoke CLI command (openfn generate adaptor ?) but I am anxious about this generate namespace. What if the monorepo's generate command called out to openfn apollo as part if its generation pipeline? So it's a monorepo task and not a CLI task?

Public Documentation

We should host user-friendly API documentation somewhere, I guess on docs.openfn.org. Probably with tutorials. Neither the CLI nor the server is mature enough for this yet.

Start by locating the Apollo CLI entry points and existing commands such as openfn apollo ls and openfn apollo help. Review how the CLI currently communicates with Apollo services, handles payloads and keys, and integrates with generation workflows. The issue contains several independent proposals, so completion is not defined until one scoped improvement and its expected behavior are selected.