Link Search Menu Expand Document

Commands (CLI) Reference

Table of contents

  1. Installing the lakectl command locally
  2. Configuring credentials and API endpoint
  3. Command Reference
    1. lakectl branch create
    2. lakectl branch delete
    3. lakectl branch list
    4. lakectl branch revert
    5. lakectl branch show
    6. lakectl commit
    7. lakectl config
    8. lakectl diff
    9. lakectl fs cat
    10. lakectl fs ls
    11. lakectl fs rm
    12. lakectl fs stat
    13. lakectl fs upload
    14. lakectl log
    15. lakectl merge
    16. lakectl repo create
    17. lakectl repo delete
    18. lakectl repo list
    19. lakectl show
    20. lakectl auth users create
    21. lakectl auth users list
    22. lakectl auth users delete
    23. lakectl auth users --id <userID> groups list
    24. lakectl auth users --id <userID> credentials list
    25. lakectl auth users --id <userID> credentials create
    26. lakectl auth users --id <userID> credentials delete
    27. lakectl auth users --id <userID> policies list
    28. lakectl auth users --id <userID> policies attach
    29. lakectl auth users --id <userID> policies detach
    30. lakectl auth groups list
    31. lakectl auth groups create
    32. lakectl auth groups delete
    33. lakectl auth groups --id <groupID> members list
    34. lakectl auth groups --id <groupID> members add
    35. lakectl auth groups --id <groupID> members remove
    36. lakectl auth groups --id <groupID> policies list
    37. lakectl auth groups --id <groupID> policies attach
    38. lakectl auth groups --id <groupID> policies detach
    39. lakectl auth policies create
    40. lakectl auth policies delete
    41. lakectl auth policies list
    42. lakectl auth policies show
    43. lakectl metastore copy
    44. lakectl metastore diff
    45. lakectl metastore create-symlink
  4. lakeFS URI pattern

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.

Download lakectl

Configuring credentials and API endpoint

Once you’ve installed the lakectl command, run:

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), the UI will provide a link to download a preconfigured configuration file for you.

Command Reference

lakectl branch create
create a new branch in a repository

Usage:
  lakectl branch create [ref uri] [flags]

Flags:
  -h, --help            help for create
  -s, --source string   source branch uri

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 branch delete
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 branch list
list branches in a repository

Usage:
  lakectl branch list [repository uri] [flags]

Examples:
lakectl branch list lakefs://myrepo

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

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 branch revert
revert changes - there are four different ways to revert changes:
  1. revert to previous commit, set HEAD of branch to given commit - revert lakefs://myrepo@master --commit commitId
  2. revert all uncommitted changes (reset) - revert lakefs://myrepo@master
  3. revert uncommitted changes under specific path -	revert lakefs://myrepo@master --prefix path
  4. revert uncommitted changes for specific object - revert lakefs://myrepo@master --object path

Usage:
  lakectl branch revert [branch uri] [flags]

Flags:
      --commit string   commit ID to revert branch to
  -h, --help            help for revert
      --object string   path to object to be reverted
      --tree string     path to tree to be reverted

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 branch show
show branch metadata

Usage:
  lakectl branch show [branch uri] [flags]

Flags:
  -h, --help   help for show

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 commit
commit changes on a given branch

Usage:
  lakectl commit [branch uri] [flags]

Flags:
  -h, --help             help for commit
  -m, --message string   commit message
      --meta strings     key value pair in the form of key=value

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
Create/update local lakeFS configuration

Usage:
  lakectl config [flags]

Flags:
  -h, --help   help for config

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 diff
see the list of paths added/changed/removed in a branch or between two references (could be either commit hash or branch name)

Usage:
  lakectl diff [ref uri] <other ref uri> [flags]

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
dump content of object to stdout

Usage:
  lakectl fs cat [path uri] [flags]

Flags:
  -h, --help               help for cat
      --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 fs ls
list entries under a given tree

Usage:
  lakectl fs ls [path uri] [flags]

Flags:
  -h, --help               help for ls
      --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 fs rm
delete object

Usage:
  lakectl fs rm [path uri] [flags]

Flags:
  -h, --help   help for rm

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 stat
view object metadata

Usage:
  lakectl fs stat [path uri] [flags]

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 fs upload
upload a local file to the specified URI

Usage:
  lakectl fs upload [path uri] [flags]

Flags:
  -h, --help            help for upload
  -s, --source string   local file to upload, 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 log
show log of commits for the given branch

Usage:
  lakectl log [branch uri] [flags]

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

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 merge
merge & commit changes from source branch into destination branch

Usage:
  lakectl merge [flags]

Flags:
  -h, --help   help for merge

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 repo create
create a new repository

Usage:
  lakectl repo create  [repository uri] [bucket name] [flags]

Flags:
  -d, --default-branch string   the default branch of this repository (default "master")
  -h, --help                    help for 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)
lakectl repo delete
delete existing repository

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 repo list
list repositories

Usage:
  lakectl repo list [flags]

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

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
See detailed information about an entity by ID (commit, user, etc)

Usage:
  lakectl show [repository uri] [flags]

Flags:
      --commit string   commit id to show
  -h, --help            help for show

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 create
create a user

Usage:
  lakectl auth users create [flags]

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 users list
list users

Usage:
  lakectl auth users 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

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
delete a user

Usage:
  lakectl auth users delete [flags]

Flags:
  -h, --help        help for delete
      --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 --id <userID> groups list
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

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 --id <userID> credentials list
create user credentials

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 users --id <userID> credentials create
create user credentials

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 users --id <userID> credentials delete
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)

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 --id <userID> policies list
list policies for the given user

Usage:
  lakectl auth users policies list [flags]

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

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 --id <userID> policies attach
attach a policy to a user

Usage:
  lakectl auth users policies attach [flags]

Flags:
  -h, --help            help for attach
      --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 --id <userID> policies detach
detach a policy from a user

Usage:
  lakectl auth users policies detach [flags]

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 groups list
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

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 create
create a group

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 groups delete
delete a group

Usage:
  lakectl auth groups delete [flags]

Flags:
  -h, --help        help for delete
      --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 groups --id <groupID> members list
list users in a group

Usage:
  lakectl auth groups members 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      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 groups --id <groupID> members add
add a user to a group

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 groups --id <groupID> members remove
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

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 --id <groupID> policies list
list policies for the given group

Usage:
  lakectl auth groups policies 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      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 groups --id <groupID> policies attach
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

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 --id <groupID> policies detach
detach a policy from a group

Usage:
  lakectl auth groups policies detach [flags]

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 policies create
create a policy

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 policies delete
delete a policy

Usage:
  lakectl auth policies delete [flags]

Flags:
  -h, --help        help for delete
      --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 list
list policies

Usage:
  lakectl auth policies 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

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

Usage:
  lakectl auth policies show [flags]

Flags:
  -h, --help        help for show
      --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 metastore copy

copy or merge table. the destination table will point to the selected branch

Usage:
  lakectl metastore copy [flags]

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 metastore diff

show column and partition differences between two tables

Usage:
  lakectl metastore diff [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]

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 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

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)

lakeFS URI pattern

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).

Their pattern is:

Repository URI: lakefs://<repository_id>
Commit URI: lakefs://<repository_id>@<ref_id>
Branch URI: lakefs://<repository_id>@<ref_id>
Object URI: lakefs://<repository_id>@<ref_id>/<object_path>

ref_id = either a commit ID or a branch ID.
    lakeFS supports using them interchangeably where it makes sense to do so