Restate CLI

[tillrohrmann]

In order to provide a better user experience for our users we believe that a CLI is required. The CLI should enable our users to effectively interact with a Restate deployment. This includes among other things:

• Obtaining cluster information (ingress, REST endpoints)
• Interacting with service endpoints
  • Registering new endpoints
  • Inspect endpoints
• Interacting with services
  • Inspect services
  • Obtain versioning information
• Interacting with invocations
  • Inspection of invocations and service state
  • Repairing of state
  • Detection of stuck invocations
  • Killing/Cancellation of invocations

Ideally, we can evolve the Restate CLI also into a CLI used by our managed service.

Tasks

Preview Give feedback

1. Define user stories for the interaction with Restate to define requirements for the CLI #889
   api-devex cli +2
   
2. Decide on technology stack for CLI #890
   api-devex cli +2
   
3. CLI flow to cancel/kill invocations #924
   api-devex cli +2
4. CLI flow to discover endpoints and services #938
   api-devex cli +2
   
5. [Draft] Restate doctor: detect and report unhealthy invocations and/or service instances
6. [Draft] Restate inspect: Grab details about any object given its ID or name
7. CLI command to run datafusion SQL queries #945
   api-devex cli +2
8. CLI download examples command #947
   api-devex cli +2
   
9. NO_INTERACTIVE env variable to fail fast interactive commands on CI #948
   cli enhancement good first issue opsex +4
10. Restate up: Easy way to get Restate started with good devex #1076
    cli +1
11. Provide convenience binaries for restate-server and cli #926
    +0
    
12. Support displaying past invocation #892
    needs-refinement +1
13. Store caller information for background invokes #997
    +0
    
14. Support inspecting and completing awakeables from the CLI #1075
    cli +1

[slinkydeveloper]

For the prototype we had build a cli tool https://github.com/restatedev/cli which did a number of things, we could also take some ideas from there (not necessarily code)

[AhmedSoliman]

The CLI can be a one-stop shop for developers and operators using restate, I imagine a cli that guides users through the getting started journey for any new project and to be a close companion in development and production time.

[tillrohrmann]

@AhmedSoliman feel free to add the next steps for how to extend the current CLI to this umbrella issue (e.g. template project creation, introspection of state and journal, etc.).

[tillrohrmann]

Latest update on the plan:

• Ship the basic "catalog" experience of the CLI before EOY. (tier 1 features)
  • The catalog experience includes discovery, list/describe services, basic status info of services (keyed and unkeyed), and same for endpoints, finding invocations that are not making progress and killing/cancelling them.
• The goal is to provide users with the basic tools they need to get through some of the potentially frustrating bits of their day0-1 experiments. Why is my invocation stuck, what's happening with a service, how busy is a service key, etc.
• not tackle the state/data introspection or patching in this iteration.
• Tentatively add support for "invoke" through the CLI, time permitting.
• Tier 2 features that might not make the cut line in this iteration are:
  • Introspection of schema types and methods
  • State/data introspection and patching
  • Restate doctor: Runs a set of internal checks and runbooks to detect common gotchas and report to the user (dead locks, endpoint health, etc.)
  • Restate inspect: Takes any id, service name, or grpc message type and prints information about it. This requires uniform internal ID schema (possibly the one proposed here)
• Before EOY, need support by adding or improving the set of datafusion/sql tables to support the CLI and we accept that the CLI will absorb the complexity of stitching information from various sources/queries to visualize.
• We agreed that the path for the future is a dedicated gRPC service "Cluster Admin Server" that provides high-fidelity APIs that supports CLI operations, and also acts as the SQL query server for the cluster. The SQL interface will be provided through the gRPC service as well. That said, this will not happen before EOY and the CLI will not wait for it, but its availability in the future is expected to dramatically improve the CLI experience by providing richer information that reduces CLI complexity.

[slinkydeveloper]

Can we close this @tillrohrmann @AhmedSoliman and just rely on the single issues?

[tillrohrmann]

I am fine with closing this issue and moving the open issues into a follow-up umbrella issue.