# Pulp 3 CLI Planning

## MVP User stories

### User

* As a CLI user, can see status of Pulp
* As a CLI user, I can provide a configuration with my authentication credentials and server address
* As a CLI user, I can reference resources by name or pulp_href.
* As a CLI user, I can see details of a task
* As a CLI user, I can cancel a running or waiting task
* As a CLI user, I am guaranteed that the CLI will wait on tasks to complete
* As a CLI user, server responses shown to me are parsed to human readable form
* As a CLI user, I can chunk upload artifacts into Pulp
* As a CLI user, I have docs on how to install, setup, and use the Pulp CLI

#### pulp_file (autogenerated)

* As a CLI user, I can CRUD file repositories
* As a CLI user, I can CRUD file remotes
* As a CLI user, I can CRUD file publications
* As a CLI user, I can CRUD file distributions
* As a CLI user, I can CRUD file content
* As a CLI user, I can create a file repository version by specifying a file repository and a file remote
* As a CLI user, I can create a file repository version by adding/removing content
* As a CLI user, I can create a file publication from a file repository or repository version
* As a CLI user, I can create a file distribution for a file publication
* As a CLI user, I can sync and publish a file repository in one command.

### Plugin writer

* As a plugin writer, I can ship custom CLI commands that are discovered by a Python entry point
* As a plugin writer, I am guaranteed that all API endpoints for a plugin are automatically available by the CLI parsing the openAPI schema
* As a plugin writer, I can use the plugin template to get a basic code structure for my CLI package
* As a plugin writer, I can use the plugin template to generate CI/CD for testing and releasing my CLI package
* As a plugin writer, I have docs on how to setup and create CLI commands

## Technical discussion

* CLI framework?
* click
* https://click.palletsprojects.com/
* Popular, well known, and stable. Uses functions and decotorators
* typer
* https://github.com/tiangolo/typer
* Wrapper around click that uses type hints
* fire
* https://github.com/google/python-fire
* Newer. Uses functions or classes. Lots of magic/implicitness.
* cliff
* https://docs.openstack.org/cliff/latest/
* Also newer. Uses classes. Might be too tied to openstack?
* Will CLI be generated statically or dynamically?
* statically definition: The code is already written, and the code is shipped with the application
* dynamically definition: commands are generated at runtime
* statically generated pro
* simple
* easier to troubleshoot
* statically generated con
* require plugins to release and ship another python package
* dynamically generated pro
* server-side features automatically become client features
* always a complete CLI matching the server-side API
* dynamically generated con
* more complicated
* We'll have to DIY it, there isn't a project out there that does it
* How will plugin writers/developers update the CLI when there is an API change?
* Example: new option or new API endpoint
* How will plugin writers/developers override options (ie rename or remove them)?
* Will the CLI interact directly with pulp or use the bindings?
* Would there be an opportunity to open source our tooling for generating Python CLIs from OpenAPI schemas?
* Versioning? For example, what if a cli is talking to two Pulp servers with different versions
* Use virtualenvs and each plugin cli package requires a particular server version
* CLI fetches version info from Pulp server and installs the needed CLI package versions in a virtualenv

### Design

#### Bindings

We imagine that the CLI will use the bindings to communicate with the Pulp server.

#### Versioning

For example, what if a cli is talking to two Pulp servers with different versions

* Use virtualenvs and each plugin cli package requires a particular server version
* CLI fetches version info from Pulp server and installs the needed CLI package versions in a virtualenv

#### Static vs Dynamic

##### Purely static

- Plugin writers use a template tool to generate commands and options from an API schema
- Tooling can be re-run to sync code when the API changes
- Plugin writers can override these commands/options in their code
- Plugins can also add extra commands

##### Hybrid

- Plugin writers use a template tool to generate commands from an API schema
- Pulp-CLI maps these commands to endpoints and fills in options at runtime
- Plugin writers can override these options in their code
- Plugins can also add extra commands
- Tooling can be re-run to sync code when the API changes

## Prototype

### Goals

- Includes a set of commands (2-3+)
- A template to generate these commands

### Technologies

- Uses click
- Use bindings
- Don't worry about installing bindings into virtualenvs for now

### Command Design

- Use only pulp_hrefs for now (don't worry about name resolution)
- Use functions or classes?
- click uses functions so that would be a natural choice
- maybe can still use class `__call__` or map methods to functions?
- Command formats?
- pulp-cli file repository create ...
- pulp-cli repository file create ...
- pulp-cli file file repository create ...
- pulp-cli repository file file create ...
- pulp-cli file repository create --type=file ...
- pulp-cli file repository --type=file create ...
* my preference, because 'file' could be a default value here
- pulp-cli rpm content packages list
- pulp-cli rpm content advisories list

#### Output format

- In which format should the cli present its result?
- Tabular
- python repr
- json
- yaml
- Is this configurable?

#### Commands to Implement

- Status
- File repository CRUD

### Generating Commands

- Use openapi generator and give it templates to generate commands
- Add these templates into pulp-openapi-generator
- Will map openapi endpoints to commands with bindings

### Pulp ansible modules

https://github.com/pulp/squeezer

- Think about sharing ideas about user stories and behaviours
- Look at sharing backend bindings code between ansible modules and CLI

## Notes from 4-AUG
User stories: https://pulp.plan.io/versions/93
Matthias' POC: https://github.com/mdellweg/pulp-cli

* Autogeneration from openapiv3 looks like it will be harder/less appropriate than we like

* Generation questions
* autogen docs are aimed at programmatic interface
* CLI needs to be human-consumable
* pulp2 CLI - no generation, all explicitly programmed
* got out of sync/incomplete
* can we attach code to generated endpoints/bindings?
* eg, squeezer work
* group cmds into logical structure
* some parts of the REST API we may not *want* to expose (eg, upload/create-content-unit/add-to-repo as 'one stop shop')
* we should always use chunked-upload

* squeezer discussion
* list of paths from openapi
* every operation has an id
* squeezer knows operations by-id
* compat-lib matches provided params-to-REST-api

* do we match CLI-version vs pulp-version?
* prob leave for later release

* use bindings? ditch bindings and use squeezer?
* ditch pros
* not have to worry about as many dependencies
* implies introspect schema directly
* how do bindings talk to server? aiohttp? can be defined

* want plugin access be as lightweight as possible
* reduce friction for plugin writer
* squeezer - inherit a class for basic CRUD
* openapiv3-python-pkg experimentation
* functions vs inheritance - click vs squeezer

* FTE estimate discussion
* 1.5 for 3 months?
* POC necessary (we'll prob throw the first one away)
* by pulpcon?
* OR, brainstorm at pulpcon, POC by end of Sept
* who can work on this and when?
* meet 30 min next week
* agenda: more design thoughts, and maybe person-commitments
* how hard is it to implement ansible-module?
* for rpm maybe?
* dkliban may find time (maybe by next week?)

* Action Items:
* ddavis to schedule mtg for next week post-3.6-release
* dkliban to try and find time to build out some rpm-support via ansible

## Notes from 26-AUG Meeting
### Action Items
* ddavis to pull together existing feedback from various communities into a doc, linked to from this doc
* Matthias to work on POC (remove binding-deps, etc)
* group to reconvene before PulpCON (2-SEP)

## Notes from 2-SEP meeting

* ddavis got feedback from RHUI, support
* doc is [here](https://docs.google.com/document/d/1LOShhGWexyuxTI_jzLAQV42p1snEIxjNdDHBYiLpnEA/edit#) - link is internal due to some of the topics discussed, apologies
* rhui
* task
* find specific RPM in specific repo-versions
* manage batches of tasks
* repo-details
* orphan-cleanup
* list-orphans
* always intended to exist, not implemented
* repo-management - list repo-sync-states, for example
* filter task by repo?
* filter by locked-resources <- better
* remove specfic nevras from custom repos
* current list-of-hrefs, but CLI needs to be more user-friendly
* human-readable access vs href
* matthias' CLI already has a PC of href-to-readable
* list parameters? what about wildcards? (not for first cut, to be sure)
* searching for content
* support
* task management
* lots of existing kbase with pulp-admin commands
* can we get a list of such articles from support?
* would help prioritize what cmds are actually in use
* repo-download/verify would be good (ie, expose 'repair')
* what about capsules?
* still won't be able to help w/dynaflow tasks?
* to-dos
* CRDL for task-management
* ddavis starting on this already
* list tasks by blocked resources - useful, does the REST API even let us do this yet?
* pulp orphan delete
* dkliban to schedule time w/mdellweg to get started on CLI
* repository work
* should be moved to pulp-org
* do we need to rename it?

###### tags: `CLI`