CLI Commands

Available Commands

Usage: nessie [OPTIONS] COMMAND [ARGS]...

  Nessie cli tool.

  Interact with Nessie branches and tables via the command line

Options:
  --json             write output in json format.
  -v, --verbose      Verbose output.
  --endpoint TEXT    Optional endpoint, if different from config file.
  --auth-token TEXT  Optional bearer auth token, if different from config file.
  --version
  --help             Show this message and exit.

Commands:
  branch       Branch operations.
  cherry-pick  Cherry-pick HASHES onto another branch.
  config       Set and view config.
  content      View, list content, and commit changes.
  diff         Show diff between two given references.
  log          Show commit log.
  merge        Merge FROM_REF into another branch.
  reflog       Show reflog.
  remote       Set and view remote endpoint.
  tag          Tag operations.

Config Command

Used to set config parameters found in default_config.yaml and to set the default context. To set default context use nessie config --add default_branch main, all operations that are ref specific will happen on that ref unless otherwise specified.

Usage: nessie config [OPTIONS] [KEY]

  Set and view config.

Options:
  --get TEXT    get config parameter
  --add TEXT    set config parameter
  -l, --list    list config parameters
  --unset TEXT  unset config parameter
  --type TEXT   type to interpret config value to set or get. Allowed options:
                bool, int
  -h, --help    Show this message and exit.

Branch Command

Perform operations on branches: create, delete, modify and reassign.

Usage: nessie branch [OPTIONS] [BRANCH] [BASE_REF]

  Branch operations.

  BRANCH name of branch to list or create/assign

  BASE_REF name of branch or tag from which to create/assign the new BRANCH

  Examples:

      nessie branch -> list all branches

      nessie branch -l -> list all branches

      nessie branch -l main -> list only main

      nessie branch -d main -> delete main

      nessie branch new_branch -> create new branch named 'new_branch' at
      current HEAD of the default branch

      nessie branch new_branch main -> create new branch named 'new_branch' at
      head of reference named 'main'

      nessie branch -o 12345678abcdef new_branch main -> create a branch named
      'new_branch' at hash 12345678abcdef on reference named 'main'

      nessie branch new_branch main@12345678abcdef -> create a branch named
      'new_branch' at hash 12345678abcdef on reference named 'main', alternate
      syntax for the above

      nessie branch -f existing_branch main -> assign branch named
      'existing_branch' to head of reference named 'main'

      nessie branch -o 12345678abcdef -f existing_branch main -> assign branch
      named 'existing_branch' to hash 12345678abcdef on reference named 'main'

Options:
  -l, --list              list branches
  -d, --delete            delete a branch
  -f, --force             force branch assignment
  -o, --hash-on-ref TEXT  Hash on source-reference for 'create' and 'assign'
                          operations, if the branch shall not point to the HEAD
                          of the given source-reference.
  -c, --condition TEXT    Expected hash. Only perform the action if the branch
                          currently points to the hash specified by this option.
  -x, --extended          Retrieve additional metadata for a branch, such as
                          number of commits ahead/behind, info about the HEAD
                          commit, number of total commits, or the common
                          ancestor hash.
  --help                  Show this message and exit.

Tag Command

Perform operations on tags: create, delete, modify and reassign.

Usage: nessie tag [OPTIONS] [TAG_NAME] [BASE_REF]

  Tag operations.

  TAG_NAME name of branch to list or create/assign

  BASE_REF name of branch or tag whose HEAD reference is to be used for the new
  tag

  Examples:

      nessie tag -> list all tags

      nessie tag -l -> list all tags

      nessie tag -l v1.0 -> list only tag "v1.0"

      nessie tag -d v1.0 -> delete tag "v1.0"

      nessie tag new_tag -> create new tag named 'new_tag' at current HEAD of
      the default branch

      nessie tag new_tag main -> create new tag named 'new_tag' at head of
      reference named 'main' (branch or tag)

      nessie tag -o 12345678abcdef new_tag test -> create new tag named
      'new_tag' at hash 12345678abcdef on reference named 'test'

      nessie tag new_tag test@12345678abcdef -> create new tag named 'new_tag'
      at hash 12345678abcdef on reference named 'test', alternative syntax of
      the above

      nessie tag -f existing_tag main -> assign tag named 'existing_tag' to head
      of reference named 'main'

      nessie tag -o 12345678abcdef -f existing_tag main -> assign tag named
      'existing_tag' to hash 12345678abcdef on reference named 'main'

Options:
  -l, --list              list branches
  -d, --delete            delete a branches
  -f, --force             force branch assignment
  -o, --hash-on-ref TEXT  Hash on source-reference for 'create' and 'assign'
                          operations, if the tag shall not point to the HEAD of
                          the given source-reference.
  -c, --condition TEXT    Expected hash. Only perform the action if the tag
                          currently points to the hash specified by this option.
  -x, --extended          Retrieve additional metadata for a tag, such as number
                          of commits ahead/behind, info about the HEAD commit,
                          number of total commits, or the common ancestor hash.
  --help                  Show this message and exit.

Remote Command

Set and view the remote. The add command is a shortcut to nessie config --set endpoint <endpoint> and the show command functions similarly to the git remote show <remote> command to show the remote and remote refs.

Usage: nessie remote [OPTIONS] COMMAND [ARGS]...

  Set and view remote endpoint.

Options:
  --help  Show this message and exit.

Commands:
  add       Set current remote.
  set-head  Set current default branch.
  show      Show current remote.

It contains the following sub-commands:

Remote Show Command

Usage: nessie remote show [OPTIONS]

  Show current remote.

Options:
  --help  Show this message and exit.

Remote Add Command

Usage: nessie remote add [OPTIONS] ENDPOINT

  Set current remote.

Options:
  --help  Show this message and exit.

Remote Set-head Command

Usage: nessie remote set-head [OPTIONS] HEAD

  Set current default branch. If -d is passed it will remove the default branch.

Options:
  -d, --delete  delete the default branch
  --help        Show this message and exit.

Log Command

View the commit log. This operates similarly to git log and shows the log in the terminals pager. Revision range is specified as <hash>..<hash> or <hash/ref>.

Usage: nessie log [OPTIONS] [REF]

  Show commit log.

  REF name of branch or tag to use to show the commit logs

  Examples:

      nessie log -> show commit logs using the configured default branch

      nessie log 1234567890abcdef -> show commit logs starting at commit
      1234567890abcdef

      nessie log dev -> show commit logs for 'dev' branch, starting at the most
      recent (HEAD) commit of 'dev'

      nessie log dev@1234567890abcdef -> show commit logs for 'dev' branch,
      starting at commit 1234567890abcdef in 'dev'

      nessie log -n 5 dev -> show commit logs for 'dev' branch limited by 5
      commits

      nessie log --revision-range 12345678abcdef..12345678efghj dev -> show
      commit logs in range of hash '12345678abcdef' and '12345678efghj' in 'dev'
      branch

      nessie log --author nessie.user dev -> show commit logs for user
      'nessie.user' in 'dev' branch

      nessie log --filter "commit.author == 'nessie_user2' || commit.author ==
      'non_existing'" dev -> show commit logs using query in 'dev' branch

      nessie log --after "2019-01-01T00:00:00+00:00" --before
      "2021-01-01T00:00:00+00:00" dev -> show commit logs between
      "2019-01-01T00:00:00+00:00" and "2021-01-01T00:00:00+00:00" in 'dev'
      branch

Options:
  -n, --number INTEGER       number of log entries to return
  --since, --after TEXT      Only include commits newer than specific date, such
                             as '2001-01-01T00:00:00+00:00'
  --until, --before TEXT     Only include commits older than specific date, such
                             as '2999-12-30T23:00:00+00:00'
  --author TEXT              Limit commits to a specific author (this is the
                             original committer). Supports specifying multiple
                             authors to filter by.
  --committer TEXT           Limit commits to a specific committer (this is the
                             logged in user/account who performed the commit).
                             Supports specifying multiple committers to filter
                             by.
  -r, --revision-range TEXT  Hash to start viewing log from. If of the form
                             '<start_hash>'..'<end_hash>' only show log for
                             given range on the particular ref that was
                             provided, the '<end_hash>' is inclusive and
                             '<start_hash>' is exclusive.
  --filter TEXT              Allows advanced filtering using the Common
                             Expression Language (CEL). An intro to CEL can be
                             found at https://github.com/google/cel-
                             spec/blob/master/doc/intro.md. Some examples with
                             usable variables 'commit.author' (string) /
                             'commit.committer' (string) / 'commit.commitTime'
                             (timestamp) / 'commit.hash' (string) /
                             'commit.message' (string) / 'commit.properties'
                             (map) are: commit.author=='nessie_author'
                             commit.committer=='nessie_committer'
                             timestamp(commit.commitTime) >
                             timestamp('2021-06-21T10:39:17.977922Z')
  -x, --extended             Retrieve all available information for the commit
                             entries. This option will also return the
                             operations for each commit and the parent hash. The
                             schema of the JSON output will then produce a list
                             of LogEntrySchema, otherwise a list of
                             CommitMetaSchema.
  --help                     Show this message and exit.

Merge Command

Perform a merge operation. This takes commits on MERGE_BRANCH which not present on branch and adds them to branch.

Usage: nessie merge [OPTIONS] [FROM_REF]

  Merge FROM_REF into another branch.

  FROM_REF can be a hash or branch.

  Examples:

      nessie merge -c 12345678abcdef dev -> merge dev to default branch with
      default branch's expected hash '12345678abcdef'

      nessie merge -b main -c 12345678abcdef dev -> merge dev to a branch named
      main with main branch's expected hash '12345678abcdef'

      nessie merge -b main -o 56781234abcdef -c 12345678abcdef dev -> merge dev
      at hash-on-ref '56781234abcdef' to main branch with main branch's expected
      hash '12345678abcdef'

      nessie merge -f -b main dev -> forcefully merge dev to a branch named main

Options:
  -b, --branch TEXT       branch to merge onto. If not supplied the default
                          branch from config is used
  -f, --force             force branch assignment
  -c, --condition TEXT    Expected hash. Only perform the action if the branch
                          currently points to the hash specified by this option.
  -o, --hash-on-ref TEXT  Hash on merge-from-reference
  --help                  Show this message and exit.

Cherry-Pick Command

Perform a cherry-pick operation. This takes the list of commits HASHES and adds them to branch.

Usage: nessie cherry-pick [OPTIONS] [HASHES]...

  Cherry-pick HASHES onto another branch.

  HASHES commit hashes to be cherry-picked from the source reference.

  Examples:

      nessie cherry-pick -c 12345678abcdef -s dev 21345678abcdef 31245678abcdef
      -> cherry pick 2 commits with commit hash '21345678abcdef'
      '31245678abcdef' from dev branch to default branch with default branch's
      expected hash '12345678abcdef'

      nessie cherry-pick -b main -c 12345678abcdef -s dev 21345678abcdef
      31245678abcdef -> cherry pick 2 commits with commit hash '21345678abcdef'
      '31245678abcdef' from dev branch to a branch named main with main branch's
      expected hash '12345678abcdef'

Options:
  -b, --branch TEXT      branch to cherry-pick onto. If not supplied the default
                         branch from config is used
  -f, --force            force branch assignment
  -c, --condition TEXT   Expected hash. Only perform the action if the branch
                         currently points to the hash specified by this option.
  -s, --source-ref TEXT  Name of the reference used to read the hashes from.
                         [required]
  --help                 Show this message and exit.

Content Command

View, list content, and commit changes.

Usage: nessie content [OPTIONS] COMMAND [ARGS]...

  View, list content, and commit changes.

Options:
  --help  Show this message and exit.

Commands:
  commit  Commit content.
  list    List content.
  view    View content.

It contains the following sub-commands:

Content List Command

Usage: nessie content list [OPTIONS]

  List content.

  Examples:

      nessie content list -r dev -> List all contents in 'dev' branch.

      nessie content list -r dev -t DELTA_LAKE_TABLE ->  List all contents in
      'dev' branch with type `DELTA_LAKE_TABLE`.

      nessie content list -r dev --filter
      "entry.namespace.startsWith('some.name.space')" -> List all contents in
      'dev' branch that start with 'some.name.space'

Options:
  -r, --ref TEXT   Branch to list from. If not supplied the default branch from
                   config is used
  -t, --type TEXT  entity types to filter on, if no entity types are passed then
                   all types are returned
  --filter TEXT    Allows advanced filtering using the Common Expression
                   Language (CEL). An intro to CEL can be found at
                   https://github.com/google/cel-spec/blob/master/doc/intro.md.
                   Some examples with usable variables 'entry.namespace'
                   (string) & 'entry.contentType' (string) are:
                   entry.namespace.startsWith('a.b.c') entry.contentType in
                   ['ICEBERG_TABLE','DELTA_LAKE_TABLE']
                   entry.namespace.startsWith('some.name.space') &&
                   entry.contentType in ['ICEBERG_TABLE','DELTA_LAKE_TABLE']
  --help           Show this message and exit.

Content View Command

Usage: nessie content view [OPTIONS] KEY...

  View content.

      KEY is the content key that is associated with a specific content to view.
      This accepts as well multiple keys with space in between. The key can be
      in this format: 'table.key' or 'namespace."table.key"'.

  Examples:

      nessie content view -r dev my_table -> View content details for content
      "my_table" in 'dev' branch.

Options:
  -r, --ref TEXT  Branch to list from. If not supplied the default branch from
                  config is used.
  --help          Show this message and exit.

Content Commit Command

Usage: nessie content commit [OPTIONS] KEY...

  Commit content.

      KEY is the content key that is associated with a specific content to
      commit. This accepts as well multiple keys with space in between. The key
      can be in this format: 'table.key' or 'namespace."table.key"'.

  Examples:

      nessie content commit -m "my awesome commit message" -r dev -c 122345abcd
      my_table -> Commit to branch 'dev' on expected hash '122345abcd' (head of
      the branch) the content from the interactive editor with the commit
      message "my awesome commit message" for content "my_table".

      nessie content commit -i -r dev -c 122345abcd my_table -> Commit to branch
      'dev' on expected hash '122345abcd' (head of the branch) the content from
      STDIN with the commit message from the interactive editor for content
      "my_table".

      nessie content commit -m "my awesome commit message" -R -r dev -c
      122345abcd my_table_1 my_table_2 -> Delete contents "my_table_1" and
      "my_table_2" from branch 'dev' on expected hash '122345abcd' and commit to
      branch 'dev" with the commit message "my awesome commit message".

Options:
  -r, --ref TEXT             Branch to commit content to. If not supplied the
                             default branch from config is used.
  -i, --stdin                Read content for --set from STDIN (separated by
                             Ctrl-D)
  -s, --expect-same-content  Send the same content both as the new and expected
                             (old contents) parameters for the edit operations
  -c, --condition TEXT       Expected hash. Only perform the action if the
                             branch currently points to the hash specified by
                             this option.  [required]
  -R, --remove-key           Delete a content.
  -m, --message TEXT         Commit message.
  --author TEXT              The author to use for the commit
  --help                     Show this message and exit.