Treat your CLI like an API

Applying the developer-friendly attributes of APIs to your command line interfaces will increase adoption of your software, make it easier to update over time, and build trust in your business.

Transcript

1. Rob Szumski
   @robszumski | Head of Design
   Treat your CLI like an API
   

   View Slide

2. Smart Datacenter
   Powered by containers
   

   View Slide

3. Automatic Updates
   

   View Slide

4. Treat your CLI like an API
   CLI API
   =
   

   View Slide

5. Why do I care about CLIs?
   ?
   

   View Slide

6. Critical Path
   

   View Slide

7. UX = Adoption = Revenue
   Embedded in a dev workflow
   But, devs need to trust it first
   

   View Slide

8. Versioning
   Plan for greater scope
   Backwards compatibility
   Deprecation/feature removal
   Great APIs...
   

   View Slide

9. Design your CLI like an API
   CLI API
   =
   

   View Slide

10. Design your CLI like an API
    CLI API
    =
    

    View Slide

11. Design your CLI like an API
    CLI API
    =
    

    View Slide

12. Design your CLI like an API
    CLI API
    = UI
    

    View Slide

13. First, a history lesson
    

    View Slide

14. Do one thing & do it well
    UNIX PHILOSOPHY
    

    View Slide

15. Users expect full solutions,
    which increases CLI scope
    

    View Slide

16. Remote services have
    unique data models
    

    View Slide

17. Developers expect many
    features with knobs to tweak
    

    View Slide

18. “Cloud native”
    

    View Slide

19. “Cloud native”
    Dynamic
    Large scope
    Remote services
    Integrated
    Security
    Release
    Cycles
    Configuration
    

    View Slide

20. Easy to configure
    Well-named commands
    Useful release notes
    Out-of-box experience
    

    View Slide

21. Versioning/backwards compatibility
    Always scriptable
    Easy to upgrade
    Document the upgrade
    Building trust
    

    View Slide

22. Living in the Critical Path
    LESSONS FROM
    

    View Slide

23. Automatic Updates
    apt/yum
    npm
    pypi
    docker
    curl | sh
    Package Managers
    

    View Slide

24. Choose smart, secure defaults
    FLAGS
    

    View Slide

25. $ mysql
    $ mysql --host=localhost --port=3306
    

    View Slide

26. $ rkt run ubuntu
    $ rkt run \
    --insecure-options=none \
    --trust-keys-from-https=false \
    ubuntu
    

    View Slide

27. Think about forward
    compatibility at the beginning
    FLAGS
    

    View Slide

28. $ rkt run
    --insecure-skip-verify \
    ubuntu
    $ rkt run
    --insecure-options=image \
    ubuntu
    $ rkt run \
    --insecure-options=image,http,pubkey \
    ubuntu
    

    View Slide

29. Scripting against a CLI should
    always be possible
    This is a hidden API contract
    CLI/API
    CONTRACT
    

    View Slide

30. $ kubectl get pods
    NAME READY STATUS RESTARTS AGE
    etcd-torus 1/1 Running 0 1d
    installer-prototype-sksfg 1/1 Running 0 13d
    nginx-router-lhdy6 1/1 Running 0 13d
    sidenav-prototype-gffv1 1/1 Running 0 6d
    tectonic-console-sd0rr 1/1 Running 0 13d
    torus-5mo0j 1/1 Running 0 1d
    torus-n4sji 1/1 Running 0 1d
    torus-p8c4z 1/1 Running 0 1d
    $ kubectl get pods | grep nginx | tr -s ' ' | cut -d ' ' -f 1
    nginx-router-lhdy6
    

    View Slide

31. Provide flags for users
    Env vars for scripts
    CLI/API
    CONTRACT
    

    View Slide

32. $ etcd \
    --listen-peer-urls http://10.0.1.10:2380 \
    --listen-client-urls http://127.0.0.1:2379
    $ ETCD_LISTEN_PEER_URLS=http://10.0.1.10:2380 \
    ETCD_LISTEN_CLIENT_URLS=http://127.0.0.1:2379 \
    etcd
    

    View Slide

33. 12:21:47 Starting etcd2...
    12:21:47 recognized and used environment variable ETCD_ADVERTISE_CLIENT_URLS=http://10.0.0.50:
    2379
    12:21:47 recognized and used environment variable ETCD_DATA_DIR=/var/lib/etcd2
    12:21:47 recognized and used environment variable ETCD_ELECTION_TIMEOUT=1200
    12:21:47 recognized and used environment variable ETCD_INITIAL_ADVERTISE_PEER_URLS=http://10.
    0.0.50:2380
    12:21:47 recognized and used environment variable ETCD_INITIAL_CLUSTER=controller=http://10.
    0.0.50:2380
    12:21:47 recognized and used environment variable ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
    12:21:47 recognized and used environment variable ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
    12:21:47 unrecognized environment variable ETCD_NAEM=controller
    12:21:47 etcd Version: 2.3.2
    12:21:47 Git SHA: ce63f10
    12:21:47 Go Version: go1.5.4
    12:21:47 Go OS/Arch: linux/amd64
    12:21:47 setting maximum number of CPUs to 1, total number of available CPUs is 1
    12:21:47 the server is already initialized as member before, starting as etcd member...
    12:21:47 listening for peers on http://0.0.0.0:2380
    12:21:47 listening for client requests on http://0.0.0.0:2379
    12:21:48 recovered store from snapshot at index 8240824
    

    View Slide

34. 12:21:47 Starting etcd2...
    12:21:47 recognized and used environment variable ETCD_ADVERTISE_CLIENT_URLS=http://10.0.0.50:
    2379
    12:21:47 recognized and used environment variable ETCD_DATA_DIR=/var/lib/etcd2
    12:21:47 recognized and used environment variable ETCD_ELECTION_TIMEOUT=1200
    12:21:47 recognized and used environment variable ETCD_INITIAL_ADVERTISE_PEER_URLS=http://10.
    0.0.50:2380
    12:21:47 recognized and used environment variable ETCD_INITIAL_CLUSTER=controller=http://10.
    0.0.50:2380
    12:21:47 recognized and used environment variable ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379
    12:21:47 recognized and used environment variable ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380
    12:21:47 unrecognized environment variable ETCD_NAEM=controller
    12:21:47 etcd Version: 2.3.2
    12:21:47 Git SHA: ce63f10
    12:21:47 Go Version: go1.5.4
    12:21:47 Go OS/Arch: linux/amd64
    12:21:47 setting maximum number of CPUs to 1, total number of available CPUs is 1
    12:21:47 the server is already initialized as member before, starting as etcd member...
    12:21:47 listening for peers on http://0.0.0.0:2380
    12:21:47 listening for client requests on http://0.0.0.0:2379
    12:21:48 recovered store from snapshot at index 8240824
    

    View Slide

35. Return info required
    for the next step
    CLI/API
    CONTRACT
    

    View Slide

36. $ kubectl create -f nginx.yaml
    Created pod nginx-router-lhdy6
    $ docker run -d ubuntu
    a736b91c5bd9627671d4fe952103b1422cc123ce40ded73703184577730fce10
    $ etcdctl member add infra3 http://10.0.1.13:2380
    added member 9bf1b35fc7761a23 to cluster
    ETCD_NAME="infra3"
    ETCD_INITIAL_CLUSTER="infra0=http://10.0.1.10:2380,infra1=http:
    //10.0.1.11:2380,infra2=http://10.0.1.12:2380,infra3=http://10.
    0.1.13:2380"
    ETCD_INITIAL_CLUSTER_STATE=existing
    

    View Slide

37. Balance scope with
    discoverability
    INFORMATION
    ARCHITECTURE
    

    View Slide

38. $ preso add-slide --title="New Slide"
    $ preso slide add --title="New Slide"
    

    View Slide

39. $ preso -h
    Usage:
    preso [flags]
    preso [command]
    Available Commands:
    add-slide
    apply-template
    delete-slide
    make-template
    present
    

    View Slide

40. $ preso -h
    Usage:
    preso [flags]
    preso [command] [subcommand]
    Available Commands:
    slide
    present
    template
    Use "preso [command] --help" for info about a command.
    

    View Slide

41. $ preso add-slide $ preso slide add
    

    View Slide

42. Build Trust
    

    View Slide

43. >
    Open-source CLIs
    

    View Slide

44. Design your CLI like an API
    CLI API
    =
    

    View Slide

45. Design your CLI like an API
    CLI API
    =
    

    View Slide

46. CoreOS is hiring!
    Rob Szumski
    Head of Design
    @robszumski
    

    View Slide