From 80e423a0f5f1685c202ee04435f611311640d085 Mon Sep 17 00:00:00 2001 From: Oz Katz Date: Tue, 9 Feb 2021 15:32:01 +0200 Subject: [PATCH] generate CLI docs automatically from command help text (#1408) --- Makefile | 3 + cmd/lakectl/cmd/completion.go | 35 +- cmd/lakectl/cmd/docs.go | 153 +++ docs/reference/commands.md | 1931 ++++++++++++++++++++++----------- 4 files changed, 1490 insertions(+), 632 deletions(-) create mode 100644 cmd/lakectl/cmd/docs.go diff --git a/Makefile b/Makefile index 5801cb6293a..1f8cb161dc8 100644 --- a/Makefile +++ b/Makefile @@ -65,6 +65,9 @@ docs: docs/assets/js/swagger.yml docs-serve: ### Serve local docs cd docs; bundle exec jekyll serve +gen-docs: go-install ## Generate CLI docs automatically + $(GOCMD) run cmd/lakectl/main.go docs > docs/reference/commands.md + gen-metastore: ## Run Metastore Code generation @thrift -r --gen go --gen go:package_prefix=github.com/treeverse/lakefs/metastore/hive/gen-go/ -o metastore/hive metastore/hive/hive_metastore.thrift diff --git a/cmd/lakectl/cmd/completion.go b/cmd/lakectl/cmd/completion.go index 272e4840c4b..2e06b266c00 100644 --- a/cmd/lakectl/cmd/completion.go +++ b/cmd/lakectl/cmd/completion.go @@ -14,32 +14,51 @@ var completionCmd = &cobra.Command{ Bash: +` + "```" + `sh $ source <(lakectl completion bash) +` + "```" + ` -# To load completions for each session, execute once: +To load completions for each session, execute once: Linux: - $ lakectl completion bash > /etc/bash_completion.d/lakectl + +` + "```" + `sh +$ lakectl completion bash > /etc/bash_completion.d/lakectl +` + "```" + ` + MacOS: - $ lakectl completion bash > /usr/local/etc/bash_completion.d/lakectl + +` + "```" + `sh +$ lakectl completion bash > /usr/local/etc/bash_completion.d/lakectl +` + "```" + ` Zsh: -# If shell completion is not already enabled in your environment you will need -# to enable it. You can execute the following once: +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: +` + "```" + `sh $ echo "autoload -U compinit; compinit" >> ~/.zshrc +` + "```" + ` -# To load completions for each session, execute once: +To load completions for each session, execute once: +` + "```" + `sh $ lakectl completion zsh > "${fpath[1]}/_lakectl" +` + "```" + ` -# You will need to start a new shell for this setup to take effect. +You will need to start a new shell for this setup to take effect. Fish: +` + "```" + `sh $ lakectl completion fish | source +` + "```" + ` -# To load completions for each session, execute once: +To load completions for each session, execute once: + +` + "```" + `sh $ lakectl completion fish > ~/.config/fish/completions/lakectl.fish +` + "```" + ` + `, DisableFlagsInUseLine: true, ValidArgs: []string{"bash", "zsh", "fish"}, diff --git a/cmd/lakectl/cmd/docs.go b/cmd/lakectl/cmd/docs.go new file mode 100644 index 00000000000..d2acc9b7e67 --- /dev/null +++ b/cmd/lakectl/cmd/docs.go @@ -0,0 +1,153 @@ +package cmd + +import ( + "bytes" + "fmt" + "io" + "os" + + "github.com/spf13/cobra" +) + +// language=markdown +var cliReferenceHeader = `--- +layout: default +title: Command (CLI) Reference +description: lakeFS comes with its own native CLI client. Here you can see the complete command reference. +parent: Reference +nav_order: 3 +has_children: false +--- + +# Commands (CLI) Reference +{: .no_toc } + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +## Installing the lakectl command locally + +` + "`" + `lakectl` + "`" + ` is distributed as a single binary, with no external dependencies - and is available for MacOS, Windows and Linux. + +[Download lakectl](../downloads.md){: .btn .btn-green target="_blank"} + + +### Configuring credentials and API endpoint + +Once you've installed the lakectl command, run: + +` + "```" + `bash +lakectl config +# output: +# Config file /home/janedoe/.lakectl.yaml will be used +# Access key ID: AKIAIOSFODNN7EXAMPLE +# Secret access key: **************************************** +# Server endpoint URL: http://localhost:8000/api/v1 +` + "```" + ` + +This will setup a ` + "`" + `$HOME/.lakectl.yaml` + "`" + ` file with the credentials and API endpoint you've supplied. +When setting up a new installation and creating initial credentials (see [Quick start](../quickstart/index.md)), the UI +will provide a link to download a preconfigured configuration file for you. + +` + +func printOptions(buf *bytes.Buffer, cmd *cobra.Command) error { + flags := cmd.NonInheritedFlags() + flags.SetOutput(buf) + if flags.HasAvailableFlags() { + buf.WriteString("#### Options\n\n```\n") + flags.PrintDefaults() + buf.WriteString("```\n\n") + } + parentFlags := cmd.InheritedFlags() + parentFlags.SetOutput(buf) + return nil +} + +// this is a version of github.com/spf13/cobra/doc that fits better +// into lakeFS' docs. +func genMarkdownForCmd(cmd *cobra.Command, w io.Writer) error { + cmd.InitDefaultHelpCmd() + cmd.InitDefaultHelpFlag() + + buf := new(bytes.Buffer) + name := cmd.CommandPath() + + buf.WriteString("### " + name + "\n\n") + + if cmd.Hidden { + buf.WriteString("**note:** This command is a lakeFS plumbing command. Don't use it unless you're really sure you know what you're doing.\n{: .note .note-warning }\n\n") + } + + buf.WriteString(cmd.Short + "\n\n") + if len(cmd.Long) > 0 { + buf.WriteString("#### Synopsis\n\n") + buf.WriteString(cmd.Long + "\n\n") + } + + if cmd.Runnable() { + buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.UseLine())) + } + + if len(cmd.Example) > 0 { + buf.WriteString("#### Examples\n\n") + buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.Example)) + } + + if err := printOptions(buf, cmd); err != nil { + return err + } + + buf.WriteString("\n\n") + _, err := buf.WriteTo(w) + if err != nil { + return err + } + + // recurse to children + for _, c := range cmd.Commands() { + err := genMarkdownForCmd(c, w) + if err != nil { + return err + } + } + + return nil +} + +var docsCmd = &cobra.Command{ + Use: "docs [outfile]", + Hidden: true, + Run: func(cmd *cobra.Command, args []string) { + writer := os.Stdout + if len(args) == 1 { + f, err := os.Create(args[0]) + if err != nil { + DieErr(err) + } + writer = f + defer func() { + err := f.Close() + if err != nil { + DieErr(err) + } + }() + } + _, err := writer.WriteString(cliReferenceHeader) + if err != nil { + DieErr(err) + } + err = genMarkdownForCmd(rootCmd, writer) + if err != nil { + DieErr(err) + } + }, +} + +//nolint:gochecknoinits +func init() { + rootCmd.AddCommand(docsCmd) +} diff --git a/docs/reference/commands.md b/docs/reference/commands.md index e1b7f607297..f66609d9270 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -16,9 +16,9 @@ has_children: false 1. TOC {:toc} -### Installing the lakectl command locally +## Installing the lakectl command locally -The `lakectl` is distributed as a single binary, with no external dependencies - and is available for MacOS, Windows and Linux. +`lakectl` is distributed as a single binary, with no external dependencies - and is available for MacOS, Windows and Linux. [Download lakectl](../downloads.md){: .btn .btn-green target="_blank"} @@ -40,894 +40,1577 @@ This will setup a `$HOME/.lakectl.yaml` file with the credentials and API endpoi When setting up a new installation and creating initial credentials (see [Quick start](../quickstart/index.md)), the UI will provide a link to download a preconfigured configuration file for you. +### lakectl -### Command Reference +A cli tool to explore manage and work with lakeFS -##### `lakectl branch create` -````text -create a new branch in a repository +#### Synopsis -Usage: - lakectl branch create [ref uri] [flags] +lakeFS is data lake management solution, allowing Git-like semantics over common object stores -Flags: - -h, --help help for create - -s, --source string source branch uri +lakectl is a CLI tool allowing exploration and manipulation of a lakeFS environment + +#### Options -Global Flags: +``` -c, --config string config file (default is $HOME/.lakectl.yaml) + -h, --help help for lakectl --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` - -##### `lakectl branch delete` -````text -delete a branch in a repository, along with its uncommitted changes (CAREFUL) +``` -Usage: - lakectl branch delete [branch uri] [flags] -Flags: - -h, --help help for delete - -y, --sure do not ask for confirmation -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +### lakectl auth -##### `lakectl branch list` -````text -list branches in a repository +manage authentication and authorization -Usage: - lakectl branch list [repository uri] [flags] +#### Synopsis -Examples: -lakectl branch list lakefs://myrepo +manage authentication and authorization including users, groups and policies -Flags: - --after string show results after this value (used for pagination) - --amount int how many results to return, or-1 for all results (used for pagination) (default -1) - -h, --help help for list +#### Options -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +``` + -h, --help help for auth +``` -##### `lakectl branch revert` -````text -Records a new commit on the branch with the reverse effect of the given commit. -Usage: - lakectl branch revert [branch uri] [commit ref] -Example: - lakectl branch revert lakefs://example-repo@example-feature a1b2c3d4 # revert commit a1b2c3d4 from branch 'example-feature' -Flags: - -h, --help help for reset -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +### lakectl auth groups -##### `lakectl branch reset` -````text -reset changes - There are four different ways to reset changes: - 1. reset to previous commit, set HEAD of branch to given commit - reset lakefs://myrepo@master --commit [commit ref] - 2. reset all uncommitted changes - reset lakefs://myrepo@master - 3. reset uncommitted changes under specific path - reset lakefs://myrepo@master --prefix path - 4. reset uncommitted changes for specific object - reset lakefs://myrepo@master --object path -Usage: - lakectl branch reset [branch uri] [flags] +manage groups -Flags: - --commit string commit ref to reset branch to - -h, --help help for reset - --object string path to object to be reset - --tree string path to tree to be reset +#### Options -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +``` + -h, --help help for groups +``` -##### `lakectl branch show` -````text -show branch metadata -Usage: - lakectl branch show [branch uri] [flags] -Flags: - -h, --help help for show +### lakectl auth groups create -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +create a group -##### `lakectl commit` -````text -commit changes on a given branch +``` +lakectl auth groups create [flags] +``` -Usage: - lakectl commit [branch uri] [flags] +#### Options -Flags: - -h, --help help for commit - -m, --message string commit message - --meta strings key value pair in the form of key=value +``` + -h, --help help for create + --id string group identifier +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` -##### `lakectl config` -````text -Create/update local lakeFS configuration -Usage: - lakectl config [flags] +### lakectl auth groups delete -Flags: - -h, --help help for config +delete a group -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +``` +lakectl auth groups delete [flags] +``` -##### `lakectl diff` -````text -see the list of paths added/changed/removed in a branch or between two references (could be either commit hash or branch name) +#### Options -Usage: - lakectl diff [ref uri] [flags] +``` + -h, --help help for delete + --id string group identifier +``` -Flags: - -h, --help help for diff -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` -##### `lakectl fs cat` -````text -dump content of object to stdout +### lakectl auth groups help -Usage: - lakectl fs cat [path uri] [flags] +Help about any command -Flags: - -h, --help help for cat - --read-uncommitted read uncommitted data (default true) +#### Synopsis -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +Help provides help for any command in the application. +Simply type groups help [path to command] for full details. -##### `lakectl fs ls` -````text -list entries under a given tree +``` +lakectl auth groups help [command] [flags] +``` -Usage: - lakectl fs ls [path uri] [flags] +#### Options -Flags: - -h, --help help for ls - --read-uncommitted read uncommitted data (default true) +``` + -h, --help help for help +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` -##### `lakectl fs rm` -````text -delete object -Usage: - lakectl fs rm [path uri] [flags] +### lakectl auth groups list -Flags: - -h, --help help for rm +list groups -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +``` +lakectl auth groups list [flags] +``` -##### `lakectl fs stat` -````text -view object metadata +#### Options -Usage: - lakectl fs stat [path uri] [flags] +``` + --after string show results after this value (used for pagination) + --amount int how many results to return (default 100) + -h, --help help for list +``` -Flags: - -h, --help help for stat - --read-uncommitted read uncommitted data (default true) -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +### lakectl auth groups members -##### `lakectl fs upload` -````text -upload a local file to the specified URI +manage group user memberships -Usage: - lakectl fs upload [path uri] [flags] +#### Options -Flags: - -h, --help help for upload - -s, --source string local file to upload, or "-" for stdin +``` + -h, --help help for members +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` -##### `lakectl log` -````text -show log of commits for the given branch +### lakectl auth groups members add -Usage: - lakectl log [branch uri] [flags] +add a user to a group -Flags: - --after string show results after this value (used for pagination) - --amount int how many results to return, or-1 for all results (used for pagination) (default -1) - -h, --help help for log +``` +lakectl auth groups members add [flags] +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +#### Options -```` +``` + -h, --help help for add + --id string group identifier + --user string user identifier to add to the group +``` -##### `lakectl merge` -````text -merge & commit changes from source branch into destination branch -Usage: - lakectl merge [flags] -Flags: - -h, --help help for merge +### lakectl auth groups members help -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +Help about any command -##### `lakectl repo create` -````text -create a new repository +#### Synopsis -Usage: - lakectl repo create [repository uri] [bucket name] [flags] +Help provides help for any command in the application. +Simply type members help [path to command] for full details. -Flags: - -d, --default-branch string the default branch of this repository (default "master") - -h, --help help for create +``` +lakectl auth groups members help [command] [flags] +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +#### Options -##### `lakectl repo delete` -````text -delete existing repository +``` + -h, --help help for help +``` -Usage: - lakectl repo delete [repository uri] [flags] -Flags: - -h, --help help for delete -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +### lakectl auth groups members list -```` +list users in a group -##### `lakectl repo list` -````text -list repositories +``` +lakectl auth groups members list [flags] +``` -Usage: - lakectl repo list [flags] +#### Options -Flags: +``` --after string show results after this value (used for pagination) - --amount int how many results to return, or-1 for all results (used for pagination) (default -1) + --amount int how many results to return (default 100) -h, --help help for list + --id string group identifier +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` -##### `lakectl show` -````text -See detailed information about an entity by ID (commit, user, etc) -Usage: - lakectl show [repository uri] [flags] +### lakectl auth groups members remove -Flags: - --commit string commit id to show - -h, --help help for show +remove a user from a group -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +``` +lakectl auth groups members remove [flags] +``` -##### `lakectl auth users create ` -```text -create a user +#### Options -Usage: - lakectl auth users create [flags] +``` + -h, --help help for remove + --id string group identifier + --user string user identifier to add to the group +``` -Flags: - -h, --help help for create - --id string user identifier -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -``` +### lakectl auth groups policies -##### `lakectl auth users list ` -```text -list users +manage group policies -Usage: - lakectl auth users list [flags] +#### Options -Flags: - --after string show results after this value (used for pagination) - --amount int how many results to return (default 100) - -h, --help help for list +``` + -h, --help help for policies +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -``` -##### `lakectl auth users delete ` -```text -delete a user +### lakectl auth groups policies attach -Usage: - lakectl auth users delete [flags] +attach a policy to a group -Flags: - -h, --help help for delete - --id string user identifier +``` +lakectl auth groups policies attach [flags] +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +#### Options ``` + -h, --help help for attach + --id string user identifier + --policy string policy identifier +``` -##### `lakectl auth users --id groups list ` -```text -list groups for the given user -Usage: - lakectl auth users groups list [flags] -Flags: - --after string show results after this value (used for pagination) - --amount int how many results to return (default 100) - -h, --help help for list - --id string user identifier +### lakectl auth groups policies detach -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +detach a policy from a group +``` +lakectl auth groups policies detach [flags] ``` +#### Options -##### `lakectl auth users --id credentials list ` -```text -create user credentials +``` + -h, --help help for detach + --id string user identifier + --policy string policy identifier +``` -Usage: - lakectl auth users credentials create [flags] -Flags: - -h, --help help for create - --id string user identifier (default: current user) -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +### lakectl auth groups policies help -``` +Help about any command -##### `lakectl auth users --id credentials create ` -```text -create user credentials +#### Synopsis -Usage: - lakectl auth users credentials create [flags] +Help provides help for any command in the application. +Simply type policies help [path to command] for full details. -Flags: - -h, --help help for create - --id string user identifier (default: current user) +``` +lakectl auth groups policies help [command] [flags] +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +#### Options ``` + -h, --help help for help +``` -##### `lakectl auth users --id credentials delete ` -```text -delete user credentials -Usage: - lakectl auth users credentials delete [flags] -Flags: - --access-key-id string access key ID to delete - -h, --help help for delete - --id string user identifier (default: current user) +### lakectl auth groups policies list -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -``` +list policies for the given group -##### `lakectl auth users --id policies list ` -```text -list policies for the given user +``` +lakectl auth groups policies list [flags] +``` -Usage: - lakectl auth users policies list [flags] +#### Options -Flags: +``` --after string show results after this value (used for pagination) --amount int how many results to return (default 100) - --effective list all distinct policies attached to the user, even through group memberships -h, --help help for list - --id string user identifier + --id string group identifier +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -``` +### lakectl auth help -##### `lakectl auth users --id policies attach ` -```text -attach a policy to a user +Help about any command -Usage: - lakectl auth users policies attach [flags] +#### Synopsis -Flags: - -h, --help help for attach - --id string user identifier - --policy string policy identifier +Help provides help for any command in the application. +Simply type auth help [path to command] for full details. -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +``` +lakectl auth help [command] [flags] +``` +#### Options + +``` + -h, --help help for help ``` -##### `lakectl auth users --id policies detach` -```text -detach a policy from a user -Usage: - lakectl auth users policies detach [flags] +### lakectl auth policies -Flags: - -h, --help help for detach - --id string user identifier - --policy string policy identifier +manage policies -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +#### Options ``` + -h, --help help for policies +``` -##### `lakectl auth groups list` -```text -list groups -Usage: - lakectl auth groups list [flags] -Flags: - --after string show results after this value (used for pagination) - --amount int how many results to return (default 100) - -h, --help help for list +### lakectl auth policies create -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +create a policy +``` +lakectl auth policies create [flags] ``` -##### `lakectl auth groups create` -```text -create a group +#### Options + +``` + -h, --help help for create + --id string policy identifier + --statement-document string JSON statement document path (or "-" for stdin) +``` -Usage: - lakectl auth groups create [flags] -Flags: - -h, --help help for create - --id string group identifier -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +### lakectl auth policies delete +delete a policy +``` +lakectl auth policies delete [flags] ``` -##### `lakectl auth groups delete` -```text -delete a group - -Usage: - lakectl auth groups delete [flags] +#### Options -Flags: +``` -h, --help help for delete - --id string group identifier + --id string policy identifier +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) + +### lakectl auth policies help + +Help about any command + +#### Synopsis + +Help provides help for any command in the application. +Simply type policies help [path to command] for full details. + +``` +lakectl auth policies help [command] [flags] ``` -##### `lakectl auth groups --id members list` -```text -list users in a group +#### Options + +``` + -h, --help help for help +``` + + + +### lakectl auth policies list + +list policies + +``` +lakectl auth policies list [flags] +``` -Usage: - lakectl auth groups members list [flags] +#### Options -Flags: +``` --after string show results after this value (used for pagination) --amount int how many results to return (default 100) -h, --help help for list - --id string group identifier +``` + -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +### lakectl auth policies show + +show a policy +``` +lakectl auth policies show [flags] ``` -##### `lakectl auth groups --id members add` -```text -add a user to a group +#### Options + +``` + -h, --help help for show + --id string policy identifier +``` -Usage: - lakectl auth groups members add [flags] -Flags: - -h, --help help for add - --id string group identifier - --user string user identifier to add to the group -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +### lakectl auth users +manage users +#### Options + +``` + -h, --help help for users ``` -##### `lakectl auth groups --id members remove` -```text -remove a user from a group -Usage: - lakectl auth groups members remove [flags] -Flags: - -h, --help help for remove - --id string group identifier - --user string user identifier to add to the group +### lakectl auth users create -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +create a user +``` +lakectl auth users create [flags] ``` -##### `lakectl auth groups --id policies list` -```text -list policies for the given group +#### Options -Usage: - lakectl auth groups policies list [flags] +``` + -h, --help help for create + --id string user identifier +``` -Flags: - --after string show results after this value (used for pagination) - --amount int how many results to return (default 100) - -h, --help help for list - --id string group identifier -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) + +### lakectl auth users credentials + +manage user credentials + +#### Options ``` + -h, --help help for credentials +``` -##### `lakectl auth groups --id policies attach` -```text -attach a policy to a group -Usage: - lakectl auth groups policies attach [flags] -Flags: - -h, --help help for attach - --id string user identifier - --policy string policy identifier +### lakectl auth users credentials create -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +create user credentials +``` +lakectl auth users credentials create [flags] ``` -##### `lakectl auth groups --id policies detach` -```text -detach a policy from a group +#### Options -Usage: - lakectl auth groups policies detach [flags] +``` + -h, --help help for create + --id string user identifier (default: current user) +``` -Flags: - -h, --help help for detach - --id string user identifier - --policy string policy identifier -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) + +### lakectl auth users credentials delete + +delete user credentials +``` +lakectl auth users credentials delete [flags] ``` +#### Options -##### `lakectl auth policies create` -```text -create a policy +``` + --access-key-id string access key ID to delete + -h, --help help for delete + --id string user identifier (default: current user) +``` -Usage: - lakectl auth policies create [flags] -Flags: - -h, --help help for create - --id string policy identifier - --statement-document string JSON statement document path (or "-" for stdin) -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +### lakectl auth users credentials help +Help about any command + +#### Synopsis + +Help provides help for any command in the application. +Simply type credentials help [path to command] for full details. + +``` +lakectl auth users credentials help [command] [flags] ``` -##### `lakectl auth policies delete` -```text -delete a policy +#### Options + +``` + -h, --help help for help +``` + + + +### lakectl auth users credentials list + +list user credentials + +``` +lakectl auth users credentials list [flags] +``` + +#### Options + +``` + --after string show results after this value (used for pagination) + --amount int how many results to return (default 100) + -h, --help help for list + --id string user identifier (default: current user) +``` + + -Usage: - lakectl auth policies delete [flags] +### lakectl auth users delete -Flags: +delete a user + +``` +lakectl auth users delete [flags] +``` + +#### Options + +``` -h, --help help for delete - --id string policy identifier + --id string user identifier +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) + + +### lakectl auth users groups + +manage user groups + +#### Options ``` + -h, --help help for groups +``` + + + +### lakectl auth users groups help + +Help about any command + +#### Synopsis + +Help provides help for any command in the application. +Simply type groups help [path to command] for full details. + +``` +lakectl auth users groups help [command] [flags] +``` + +#### Options + +``` + -h, --help help for help +``` + -##### `lakectl auth policies list` -```text -list policies -Usage: - lakectl auth policies list [flags] +### lakectl auth users groups list -Flags: +list groups for the given user + +``` +lakectl auth users groups list [flags] +``` + +#### Options + +``` --after string show results after this value (used for pagination) --amount int how many results to return (default 100) -h, --help help for list + --id string user identifier +``` -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -``` -##### `lakectl auth policies show` -```text -show a policy +### lakectl auth users help -Usage: - lakectl auth policies show [flags] +Help about any command -Flags: - -h, --help help for show - --id string policy identifier +#### Synopsis -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +Help provides help for any command in the application. +Simply type users help [path to command] for full details. +``` +lakectl auth users help [command] [flags] ``` -#### `lakectl metastore copy` -````text -copy or merge table. the destination table will point to the selected branch +#### Options -Usage: - lakectl metastore copy [flags] +``` + -h, --help help for help +``` -Flags: - --catalog-id string Glue catalog ID - --from-schema string source schema name - --from-table string source table name - -h, --help help for copy - --metastore-uri string Hive metastore URI - -p, --partition strings partition to copy - --serde string serde to set copy to [default is to-table] - --to-branch string lakeFS branch name - --to-schema string destination schema name [default is from-branch] - --to-table string destination table name [default is from-table] - --type string metastore type [hive, glue] -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) -```` +### lakectl auth users list -#### `lakectl metastore diff` -````text -show column and partition differences between two tables +list users -Usage: - lakectl metastore diff [flags] +``` +lakectl auth users list [flags] +``` -Flags: - --catalog-id string Glue catalog ID - --from-schema string source schema name - --from-table string source table name - -h, --help help for diff - --metastore-uri string Hive metastore URI - --to-schema string destination schema name - --to-table string destination table name [default is from-table] - --type string metastore type [hive, glue] +#### Options -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +``` + --after string show results after this value (used for pagination) + --amount int how many results to return (default 100) + -h, --help help for list +``` -```` -#### `lakectl metastore create-symlink` -````text -create table with symlinks, and create the symlinks in s3 in order to access from external devices that could only access s3 directly (e.g athena) -Usage: - lakectl metastore create-symlink [flags] -Flags: - --branch string lakeFS branch name - --catalog-id string Glue catalog ID - --from-schema string source schema name - --from-table string source table name - -h, --help help for create-symlink - --path string path to table on lakeFS - --repo string lakeFS repository name - --to-schema string destination schema name - --to-table string destination table name +### lakectl auth users policies -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +manage user policies -```` +#### Options -#### `lakectl export get ` -````text -get continuous export configuration for branch +``` + -h, --help help for policies +``` -Usage: - lakectl export get [flags] -Flags: - -h, --help help for get -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - -f, --force without prompting for confirmation - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +### lakectl auth users policies attach + +attach a policy to a user + +``` +lakectl auth users policies attach [flags] +``` -```` +#### Options -#### `lakectl export set ` -````text -set continuous export configuration for branch +``` + -h, --help help for attach + --id string user identifier + --policy string policy identifier +``` -Usage: - lakectl export set [flags] -Flags: - -h, --help help for set - --path string export objects to this path - --prefix-regex stringArray list of regexps of keys to exported last in each prefix (for signalling) - --status-path string write export status object to this path -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - -f, --force without prompting for confirmation - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +### lakectl auth users policies detach -```` +detach a policy from a user + +``` +lakectl auth users policies detach [flags] +``` + +#### Options + +``` + -h, --help help for detach + --id string user identifier + --policy string policy identifier +``` -#### `lakectl export run ` -````text -export requested branch now -Usage: - lakectl export run [flags] -Flags: - -h, --help help for run +### lakectl auth users policies help -Global Flags: - -c, --config string config file (default is $HOME/.lakectl.yaml) - -f, --force without prompting for confirmation - --no-color don't use fancy output colors (default when not attached to an interactive terminal) +Help about any command -```` -### lakeFS URI pattern +#### Synopsis -Different CLI and UI operations use `lakefs://` URIs. -These are resource identifiers used to indicate a certain resource within the system (repository, branch/commit id, object). +Help provides help for any command in the application. +Simply type policies help [path to command] for full details. -Their pattern is: +``` +lakectl auth users policies help [command] [flags] +``` -```text -Repository URI: lakefs:// -Commit URI: lakefs://@ -Branch URI: lakefs://@ -Object URI: lakefs://@/ +#### Options -ref_id = either a commit ID or a branch ID. - lakeFS supports using them interchangeably where it makes sense to do so ``` + -h, --help help for help +``` + + + +### lakectl auth users policies list + +list policies for the given user + +``` +lakectl auth users policies list [flags] +``` + +#### Options + +``` + --after string show results after this value (used for pagination) + --amount int how many results to return (default 100) + --effective list all distinct policies attached to the user, even through group memberships + -h, --help help for list + --id string user identifier +``` + + + +### lakectl branch + +create and manage branches within a repository + +#### Synopsis + +Create delete and list branches within a lakeFS repository + +#### Options + +``` + -h, --help help for branch +``` + + + +### lakectl branch create + +create a new branch in a repository + +``` +lakectl branch create [flags] +``` + +#### Options + +``` + -h, --help help for create + -s, --source string source branch uri +``` + + + +### lakectl branch delete + +delete a branch in a repository, along with its uncommitted changes (CAREFUL) + +``` +lakectl branch delete [flags] +``` + +#### Options + +``` + -h, --help help for delete + -y, --yes Automatically say yes to all confirmations +``` + + + +### lakectl branch help + +Help about any command + +#### Synopsis + +Help provides help for any command in the application. +Simply type branch help [path to command] for full details. + +``` +lakectl branch help [command] [flags] +``` + +#### Options + +``` + -h, --help help for help +``` + + + +### lakectl branch list + +list branches in a repository + +``` +lakectl branch list [flags] +``` + +#### Examples + +``` +lakectl branch list lakefs:// +``` + +#### Options + +``` + --after string show results after this value (used for pagination) + --amount int how many results to return, or-1 for all results (used for pagination) (default -1) + -h, --help help for list +``` + + + +### lakectl branch reset + +reset changes to specified commit, or reset uncommitted changes - all changes, or by path + +#### Synopsis + +reset changes. There are four different ways to reset changes: + 1. reset to previous commit, set HEAD of branch to given commit - reset lakefs://myrepo@master --commit commitId + 2. reset all uncommitted changes - reset lakefs://myrepo@master + 3. reset uncommitted changes under specific path - reset lakefs://myrepo@master --prefix path + 4. reset uncommitted changes for specific object - reset lakefs://myrepo@master --object path + +``` +lakectl branch reset [flags] +``` + +#### Options + +``` + --commit string commit ID to reset branch to + -h, --help help for reset + --object string path to object to be reset + --prefix string prefix of the objects to be reset + -y, --yes Automatically say yes to all confirmations +``` + + + +### lakectl branch revert + +given a commit, record a new commit to reverse the effect of this commit + +``` +lakectl branch revert [flags] +``` + +#### Options + +``` + -h, --help help for revert + -m, --parent-number int the parent number (starting from 1) of the mainline. The revert will reverse the change relative to the specified parent. + -y, --yes Automatically say yes to all confirmations +``` + + + +### lakectl branch show + +show branch latest commit reference + +``` +lakectl branch show [flags] +``` + +#### Options + +``` + -h, --help help for show +``` + + + +### lakectl cat-sst + +**note:** This command is a lakeFS plumbing command. Don't use it unless you're really sure you know what you're doing. +{: .note .note-warning } + +Explore lakeFS .sst files + +``` +lakectl cat-sst [flags] +``` + +#### Options + +``` + --amount int how many records to return, or -1 for all records (default -1) + -f, --file string path to an sstable file, or "-" for stdin + -h, --help help for cat-sst +``` + + + +### lakectl commit + +commit changes on a given branch + +``` +lakectl commit [flags] +``` + +#### Options + +``` + -h, --help help for commit + -m, --message string commit message + --meta strings key value pair in the form of key=value +``` + + + +### lakectl completion + +Generate completion script + +#### Synopsis + +To load completions: + +Bash: + +```sh +$ source <(lakectl completion bash) +``` + +To load completions for each session, execute once: +Linux: + +```sh +$ lakectl completion bash > /etc/bash_completion.d/lakectl +``` + +MacOS: + +```sh +$ lakectl completion bash > /usr/local/etc/bash_completion.d/lakectl +``` + +Zsh: + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + +```sh +$ echo "autoload -U compinit; compinit" >> ~/.zshrc +``` + +To load completions for each session, execute once: +```sh +$ lakectl completion zsh > "${fpath[1]}/_lakectl" +``` + +You will need to start a new shell for this setup to take effect. + +Fish: + +```sh +$ lakectl completion fish | source +``` + +To load completions for each session, execute once: + +```sh +$ lakectl completion fish > ~/.config/fish/completions/lakectl.fish +``` + + + +``` +lakectl completion +``` + +#### Options + +``` + -h, --help help for completion +``` + + + +### lakectl config + +create/update local lakeFS configuration + +``` +lakectl config [flags] +``` + +#### Options + +``` + -h, --help help for config +``` + + + +### lakectl diff + +diff between commits/hashes + +#### Synopsis + +see the list of paths added/changed/removed in a branch or between two references (could be either commit hash or branch name) + +``` +lakectl diff [other ref uri] [flags] +``` + +#### Options + +``` + -h, --help help for diff +``` + + + +### lakectl docs + +**note:** This command is a lakeFS plumbing command. Don't use it unless you're really sure you know what you're doing. +{: .note .note-warning } + + + +``` +lakectl docs [outfile] [flags] +``` + +#### Options + +``` + -h, --help help for docs +``` + + + +### lakectl fs + +view and manipulate objects + +#### Options + +``` + -h, --help help for fs +``` + + + +### lakectl fs cat + +dump content of object to stdout + +``` +lakectl fs cat [flags] +``` + +#### Options + +``` + -h, --help help for cat +``` + + + +### lakectl fs help + +Help about any command + +#### Synopsis + +Help provides help for any command in the application. +Simply type fs help [path to command] for full details. + +``` +lakectl fs help [command] [flags] +``` + +#### Options + +``` + -h, --help help for help +``` + + + +### lakectl fs ls + +list entries under a given tree + +``` +lakectl fs ls [flags] +``` + +#### Options + +``` + -h, --help help for ls +``` + + + +### lakectl fs rm + +delete object + +``` +lakectl fs rm [flags] +``` + +#### Options + +``` + -h, --help help for rm +``` + + + +### lakectl fs stat + +view object metadata + +``` +lakectl fs stat [flags] +``` + +#### Options + +``` + -h, --help help for stat +``` + + + +### lakectl fs upload + +upload a local file to the specified URI + +``` +lakectl fs upload [flags] +``` + +#### Options + +``` + -h, --help help for upload + -r, --recursive recursively copy all files under local source + -s, --source string local file to upload, or "-" for stdin +``` + + + +### lakectl help + +Help about any command + +#### Synopsis + +Help provides help for any command in the application. +Simply type lakectl help [path to command] for full details. + +``` +lakectl help [command] [flags] +``` + +#### Options + +``` + -h, --help help for help +``` + + + +### lakectl log + +show log of commits for the given branch + +``` +lakectl log [flags] +``` + +#### Options + +``` + --after string show results after this value (used for pagination) + --amount int how many results to return, or-1 for all results (used for pagination) (default -1) + -h, --help help for log + --show-meta-range-id also show meta range ID +``` + + + +### lakectl merge + +merge + +#### Synopsis + +merge & commit changes from source branch into destination branch + +``` +lakectl merge [flags] +``` + +#### Options + +``` + -h, --help help for merge +``` + + + +### lakectl metastore + +manage metastore commands + +#### Options + +``` + -h, --help help for metastore +``` + + + +### lakectl metastore copy + +copy or merge table + +#### Synopsis + +copy or merge table. the destination table will point to the selected branch + +``` +lakectl metastore copy [flags] +``` + +#### Options + +``` + --catalog-id string Glue catalog ID + --from-schema string source schema name + --from-table string source table name + -h, --help help for copy + --metastore-uri string Hive metastore URI + -p, --partition strings partition to copy + --serde string serde to set copy to [default is to-table] + --to-branch string lakeFS branch name + --to-schema string destination schema name [default is from-branch] + --to-table string destination table name [default is from-table] + --type string metastore type [hive, glue] +``` + + + +### lakectl metastore create-symlink + +create symlink table and data + +#### Synopsis + +create table with symlinks, and create the symlinks in s3 in order to access from external services that could only access s3 directly (e.g athena) + +``` +lakectl metastore create-symlink [flags] +``` + +#### Options + +``` + --branch string lakeFS branch name + --catalog-id string Glue catalog ID + --from-schema string source schema name + --from-table string source table name + -h, --help help for create-symlink + --path string path to table on lakeFS + --repo string lakeFS repository name + --to-schema string destination schema name + --to-table string destination table name +``` + + + +### lakectl metastore diff + +show column and partition differences between two tables + +``` +lakectl metastore diff [flags] +``` + +#### Options + +``` + --catalog-id string Glue catalog ID + --from-schema string source schema name + --from-table string source table name + -h, --help help for diff + --metastore-uri string Hive metastore URI + --to-schema string destination schema name + --to-table string destination table name [default is from-table] + --type string metastore type [hive, glue] +``` + + + +### lakectl metastore help + +Help about any command + +#### Synopsis + +Help provides help for any command in the application. +Simply type metastore help [path to command] for full details. + +``` +lakectl metastore help [command] [flags] +``` + +#### Options + +``` + -h, --help help for help +``` + + + +### lakectl refs-dump + +**note:** This command is a lakeFS plumbing command. Don't use it unless you're really sure you know what you're doing. +{: .note .note-warning } + +dumps refs (branches, commits, tags) to the underlying object store + +``` +lakectl refs-dump [flags] +``` + +#### Options + +``` + -h, --help help for refs-dump +``` + + + +### lakectl repo + +manage and explore repos + +#### Options + +``` + -h, --help help for repo +``` + + + +### lakectl repo create + +create a new repository + +``` +lakectl repo create [flags] +``` + +#### Options + +``` + -d, --default-branch string the default branch of this repository (default "master") + -h, --help help for create +``` + + + +### lakectl repo delete + +delete existing repository + +``` +lakectl repo delete [flags] +``` + +#### Options + +``` + -h, --help help for delete + -y, --yes Automatically say yes to all confirmations +``` + + + +### lakectl repo help + +Help about any command + +#### Synopsis + +Help provides help for any command in the application. +Simply type repo help [path to command] for full details. + +``` +lakectl repo help [command] [flags] +``` + +#### Options + +``` + -h, --help help for help +``` + + + +### lakectl repo list + +list repositories + +``` +lakectl repo list [flags] +``` + +#### Options + +``` + --after string show results after this value (used for pagination) + --amount int how many results to return, or-1 for all results (used for pagination) (default -1) + -h, --help help for list +``` + + + +### lakectl show + +See detailed information about an entity by ID (commit, user, etc) + +``` +lakectl show [flags] +``` + +#### Options + +``` + --commit string commit ID to show + -h, --help help for show + --show-meta-range-id when showing commits, also show meta range ID +``` + + + +### lakectl tag + +create and manage tags within a repository + +#### Synopsis + +Create delete and list tags within a lakeFS repository + +#### Options + +``` + -h, --help help for tag +``` + + + +### lakectl tag create + +create a new tag in a repository + +``` +lakectl tag create [flags] +``` + +#### Options + +``` + -h, --help help for create +``` + + + +### lakectl tag delete + +delete a tag from a repository + +``` +lakectl tag delete [flags] +``` + +#### Options + +``` + -h, --help help for delete +``` + + + +### lakectl tag help + +Help about any command + +#### Synopsis + +Help provides help for any command in the application. +Simply type tag help [path to command] for full details. + +``` +lakectl tag help [command] [flags] +``` + +#### Options + +``` + -h, --help help for help +``` + + + +### lakectl tag list + +list tags in a repository + +``` +lakectl tag list [flags] +``` + +#### Examples + +``` +lakectl tag list lakefs:// +``` + +#### Options + +``` + --after string show results after this value (used for pagination) + --amount int how many results to return, or-1 for all results (used for pagination) (default -1) + -h, --help help for list +``` + + + +### lakectl tag show + +show tag's commit reference + +``` +lakectl tag show [flags] +``` + +#### Options + +``` + -h, --help help for show +``` + + +