influxdata / influxdata/influx-cli

Reorganize the hierarchy of the CLI to be more action oriented

Open
#85 9 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Go
Stars
75
Forks
22
PR merge metrics
No merged PRs in 30d

Description

$ influx get buckets
$ influx export
$ influx apply pkg
$ influx config ...

instead of having the rest hierarchy we have now, we orient it around the action users want to take. I think it supports what you are after more so than cobbling it together in its current shape.

@jsteenb2 can add additional details here.

additional details from @jsteenb2:

Influx CLI proposal

This proposal is advocating for action/verb oriented commands.
At the time of writing this, the CLI is more or less a mirror of the resource heirarchy of the REST API.
I am submitting that we can change up this workflow in the CLI, to minimize command bloat, standardize inputs/outputs, and make it simpler to extend the CLI to support additional features.
In addition, we can support the existing CLI while we transition, but while we are in beta, we can deprecate these and sunset them early in the v2 GA release cycle, if not before.

New Commands

influx list cmd
influx list|ls [resource command] [--name --id]

Both --json and --hide-headers flags are still supported in addition to the --token, --host and org flags.

The list command will have the following subcommands:

influx list buckets

influx list labels

influx list organizations|orgs

influx list secrets

influx list tasks

influx list telegrafs

influx list authorizations|auth

API for list command does not limit how many filters you can use.
The API should allow the user to filter single record or all of them.
Follows same output mechanics with table/json out.

influx list buckets --name=Name1 --name=Name2 --id=ID1 --id=ID2

The CLI should also extend list commands to support args where we inspect the arg to see if it is a valid ID.
If arg is a valid ID then uses it to filter results.
If it is not then the arg is assumed a name and uses it to filter results.
If both args and flags are used, then the CLI should work all the same.

influx list buckets Name1 Name2 ID1 ID2

If no args or flags are provided, then the list command returns all entities.
Paginating as needed, while writing to stdout after each page.

influx list buckets
influx apply command
influx apply [resource command] [pkg flags]

The influx apply command and all its sub commands take piped inputs in the form of a package.

The base command is equivalent to the influx pkg command.

influx apply --file PATH_TO_PKG --url URL_TO_PKG ... other flags

The available sub commands are:

influx apply bucket

influx apply label

influx apply organization|org

influx apply pkg

influx apply secret

influx apply task

influx apply telegraf

influx apply authorization|auth

For all resource sub commands they can provide input via flags for creating or updating a resource.
When an id is provided, the command will update the existing resource identified by its ID and will update it to the specification provided.

# apply and create a bucket from pkg via piped input
cat pkg.yml | influx apply bucket

# apply and create a bucket via file input
influx apply bucket --file PATH_TO_PKG

# apply and create a new bucket via flags
influx apply bucket --name BUCKET_NAME --retention-period 24h

# apply and update existing bucket via flags
influx apply bucket --id BUCKET_ID --name BUCKET_NAME --retention-period 24h  

When providing a pkg, that has more than just buckets in it, the pkg will apply all buckets from that package and any associations outlined in it (aka labels).

influx remove command
influx remove|rm [resource command] [--force]

Available resource sub commands:

influx remove authorization|auth

influx remove bucket

influx remove label

influx remove organization|org

influx remove secret

influx remove stack

influx remove task

influx remove telegraf

Each sub command should support taking args via flags and or arguments.

# remove by --id flag
influx remove bucket --id $BUCKET_ID

# remove by --name flag
influx remove bucket --name $BUCKET_NAME

# remove by input arg being ID
influx remove bucket $BUCKET_ID 

# remove by input arg of bucket name
influx remove bucket $BUCKET_NAME

# mix of names, ids, flags
# this sample removes up to 4 buckets if names and ids are all unique
influx remove bucket \
    --id $BUCKET_ID_1 \
    --name $BUCKET_NAME_1 \
    $BUCKET_ID_2 $BUCKET_NAME_2

All remove commands should ask for confirmation if the --force flag is not provided

influx export command

The export command is used to export existing resources in the form of a package.

influx export [command] [existing flags]

Export has the following sub command(s):

influx export all [existing flags]

# potential sub commands by resource (if desired)
influx export buckets

influx export checks

influx export dashboards

influx export endpoints

influx export labels

influx export tasks

influx export telegraf-configs|telegrafs

influx export variables
influx convert command

The convert command takes a raw input and turns it into a package.
The first example would be to convert a telegraf configuration into a package.
Other examples like converting non-influx v2 platform resources (v1 -> v2 resources, grafana dashboards -> v2 dashboards, etc).

Existing commands which are all action/verb based which will remain unchanged

influx CLI specific commands

influx completion

influx config

influxd ping

influx ping

query commands

influx query

influx repl

influx transpile

setup command

influx setup

write commands

influx backup

influx delete

influx write

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No files, entry points, or tests are named. Start by comparing the existing CLI resource hierarchy with the proposed list, apply, remove, export, and convert commands; done means the action-oriented workflow and its stated aliases, inputs, outputs, confirmations, and transition support are implemented.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.