Overview

This section provides a reference sheet for all the commands provided by the rgclone CLI tool.

Global flags and parameters

While every command has a set of dedicated key value parameters and flags that drive its behaviour, rgclone also has a set of global flags and parameters that can be applied to all commands (or subset of commands).

# Create a data-container using a more verbose logging
terminal > ./rgclone create dc -i 2 --log debug 

# Normal mode
terminal > ./rgclone get di        
ID                  Name                Tags         Engine                         Status              CreatedAt           ExpiresAt
2                   testgradimage1                   MSSQL:2019-CU14-ubuntu-20.04   Completed           21 hours ago        Never
4                   testgradimage1                   MSSQL:2019-CU14-ubuntu-20.04   Completed           21 hours ago        Never

# Quiet mode
terminal > ./rgclone get di --quiet
2
4 

# Default: With table headers
terminal > ./rgclone get di                
ID                  Name               Tags          Engine                         Status              CreatedAt           ExpiresAt
4                   graduate-1                       MSSQL:2019-CU14-ubuntu-20.04   Completed           2 days ago          Never
6                   graduate-1                       PostgreSQL:14.1                Completed           2 days ago          Never

# Without table headers ('--no-table-headers' flag)
terminal > ./rgclone get di --no-table-headers
4                   graduate-1                       MSSQL:2019-CU14-ubuntu-20.04   Completed           2 days ago          Never
6                   graduate-1                       PostgreSQL:14.1                Completed           2 days ago          Never

# Normal output
terminal > ./rgclone get di 
ID                  Name                Tags                Engine                         Status              CreatedAt           ExpiresAt
2                   testgradimage1                          MSSQL:2019-CU14-ubuntu-20.04   Completed           21 hours ago        Never

# Wide output: More columns displayed
# NOTE: Column width reduced for display purposes
terminal > ./rgclone get di -o wide
ID    Name              Tags    Engine                         SourceType   Status      CreatedAt      ExpiresAt  Owner   Size       IsPublic
2     testgradimage1            MSSQL:2019-CU14-ubuntu-20.04   Graduated    Completed   21 hours ago   Never              Unknown    false

# Json output
terminal > ./rgclone get di -o json
[{"id":2,"name":"testgradimage1","engine":"MSSQL","engineVersion":"2019-CU14-ubuntu-20.04",
"sourceType":"Graduated","statusMessage":"Created data image 'testgradimage1' (2)","createdAt":1646047463,
"Owner":true,"ownerName":"","tags":[],"sizeInKb":-1,"expiresAt":0,"isPublic":false,"status":"Completed"}]

# Yaml output
terminal > ./rgclone get di -o yaml
- id: 2
  name: testgradimage1
  engine: MSSQL
  engineversion: 2019-CU14-ubuntu-20.04
  sourcetype: Graduated
  status: 2
  statusmessage: Created data image 'testgradimage1' (2)
  createdat: 1646047463
  owner: true
  ownername: ""
  tags: []
  sizeinkb: -1
  expiresat: 0
  ispublic: false

Exit codes

rgclone will return the following exit codes when running commands, where with few exceptions only success (0) will indicate a positive outcome:

Exit code	Designation	Command Status	When
0	Success		Used when a rgclone command completed successfully.
1	UnexpectedError		Used when no other error code is suitable. It's the default error code.
2	ResourceNotFound		Used when a resource (e.g. data image or data container) could not be found. Can be an error (e.g. you try to get a non-existent data image or container – e.g. rgclone get dc 17) or not (rgclone get di will return 2 when no data images exist).
3	UnrecognisedCommand		Used when a requested command is not recognised (e.g. rgclone idonotexist).
4	OperationFailed		Used when a rgclone operation failed (usually server-side).
5	OutputError		Used when an error occurred while writing to the output stream.
6	ResourceNotSpecified		Used when a resource (e.g. data image or data container) was not specified for an operation.
7	AuthenticationFailed		Used when an authentication operation failed (in any rgclone command, not only auth).
8	CtlError		Used when an error occurred while configuring the rgclone tool itself. This is typically an internal only error and in that case indicates a bug in the product.
9	ForbiddenError		Used when a user does not have access to the requested resource (e.g. data image or data container) or operation (e.g. delete).
10	UpdateCheckError		Triggered when the rgclone check for update fails (typically when communications with the server are not successful).

Please check our CLI Troubleshooting section for some known error use cases.

rgclone logging

rgclone has two types of logging, both stored locally under the same root folder:

The filename for both cases uses the following date sortable format: rgclone.YYYYMMDD.log (e.g. rgclone.20220329.log).

Daily file rotation is implemented in rgclone and old log files will be automatically purged after 30 days.

Commands

auth

Authenticate against the Web API server using either the provided access token or triggering a browser-based OIDC device flow authentication.

The token can be retrieved from the Admin Console. Please check Authenticate CLI against API Server for more details.

Command

# OIDC device flow authentication (developers)
rgclone auth

# Token based authentication (CI/CD pipelines)
rgclone auth -t "<access-token>"

create data-image

For Redgate Clone to create a database to work against, you'll first need to create a data image with this command.

Command

rgclone create data-image -f ./development.yaml

To override any tags specified in the .yaml image definition file, use the --tag option:

rgclone create data-image -f ./development.yaml --tag v1.0

To override the name specified in the .yaml image definition file, use the --name option:

rgclone create data-image -f ./development.yaml --name new-name

get data-image

You can review your data images by using the get command.

Commands

rgclone get data-images

rgclone get data-image <ImageName[:Tag]_Or_ImageID>

delete data-image

To delete a data image you can use the delete command. You cannot delete data images that have data containers.

Command

rgclone delete data-image <ImageNames[:Tag]_Or_ImageIDs>

Examples

# Delete a data image with id 10001
rgclone delete data-image 10001

# Delete multiple data images with ids 10001, 10002 and 10003
rgclone delete data-image 10001 10002 10003

# Delete a data image with name dev
rgclone delete data-image dev

# Delete multiple data images with names dev1, dev2
rgclone delete data-image dev1 dev2

# Delete data image named dev and with tag testing
rgclone delete data-image dev:testing

update data-image

You can update your data images to add or remove tags, add or remove users to share the image with, or update its lifetime by using the update command.

Commands

rgclone update data-image <ImageName[:Tag]_Or_ImageID> --tag <Tag1> --tag <Tag2>

rgclone update data-image <ImageName[:Tag]_Or_ImageID> --tag <Tag1> --remove

rgclone update data-image <ImageName[:Tag]_Or_ImageID> --user <User1> --user <User2>

rgclone update data-image <ImageName[:Tag]_Or_ImageID> --user <User1> --remove

rgclone update data-image <ImageName[:Tag]_Or_ImageID> --lifetime 2h

create data-container

You'll need to create a data container to actually spawn a database to work against. A data container is created from a data image.

You can shorten data-container to just dc.

Command

rgclone create data-container --image <ImageName[:Tag]_Or_ImageID>

--image

-i

--name

-n

--lifetime

-t

--connectionStringFormat

-c

Examples

# Create data container from image 3 that will expire in 20 minutes
rgclone create dc -i 3 -t 20m

# Create data container called dev-sql-server from the empty-mssql image that will expire
# in 2 hours and return the connection string in jdbc format
rgclone create dc -i empty-mssql -n dev-sql-server -t 2h -c jdbc

get data-container

You can review your data container by using the get command.

Commands

rgclone get data-containers

rgclone get data-container <ContainerName_Or_ContainerID>

You can change the output format when getting data containers to return more information. -o json will print the data container information out as JSON, including connection details (hostname, port, username, password). This makes it easier to consume rgclone as part of a startup script for an application as you can dynamically configure database connection details.

rgclone get data-container <ContainerName_Or_ContainerID> -o json

Examples

# Get all data containers you own
rgclone get data-containers

# Get specific data containers you own
rgclone get data-container 10001

delete data-container

To delete a data container use the delete command.

Command

rgclone delete data-container <ContainerNames_Or_ContainerIDs>

Examples

# Delete a data container with id 10001
rgclone delete data-container 10001

# Delete multiple data containers with ids 10001, 10002 and 10003
rgclone delete data-container 10001 10002 10003

# Delete a data container with name dev
rgclone delete data-container dev

# Delete multiple data containers with names dev1, dev2
rgclone delete data-container dev1 dev2

update data-container

You can update your data containers to change their lifetime by using the update command.

Command

rgclone update data-container <ContainerName_Or_ContainerID> --lifetime <LifetimeDurationString>

To rename an existing data container use the --name option:

rgclone update data-container <OldContainerName_Or_ContainerID> --name <NewContainerName>

save data-container

Saving a data container creates a new revision for that data container. To save a data container use the save command. Revisions are necessary for operations like reset, graduate and load.

Command

rgclone save data-container <ContainerName_Or_ContainerID>

reset data-container

Resetting a data container allows you to remove all changes (schema and data) made to it since the last revision.

This is useful when you want to discard the last changes you have made, especially ones that would be difficult to revert otherwise (e.g. dropping a table with data).

Command

rgclone reset data-container <ContainerNames_Or_ContainerIDs>

Examples

# Reset a data container with id 10001
rgclone reset data-container 10001

# Reset a data container with name dev
rgclone reset data-container dev

# Reset multiple data containers with ids 10001, 10002 and 10003
rgclone reset data-container 10001 10002 10003

# Reset multiple data containers with names dev1, dev2
rgclone reset data-container dev1 dev2

load data-container

Loading a data container allows you to run your data container (database) with the data saved at an earlier moment in time.

Command

rgclone load data-container <ContainerName_Or_ContainerID> --revision=<RevisionID>

graduate data-container

Overview

Graduating a data container allows you to create a data image from it. This is useful when you make changes to a data container and want to use its current state as the baseline for future work.

A good example of when to use the graduate command would be when you were able to reproduce a bug and want to share the state of your database with others. You can graduate the data container and share the resulting data image with your team.

Command

rgclone graduate data-container <ContainerName_Or_ContainerID> --revision <RevisionID> [--name <GraduatedImageName> --tag <Tag1>]

logs data-container

Using rgclone, you can get the logs of a running data container.

Command

rgclone logs data-container <ContainerName_Or_ContainerID>

proxy data-container

Running rgclone proxy data-container <container> will configure a localhost proxy on your machine on the default port for the database engine your data container is running on.

For example, if you have a Postgres data container already running, rgclone proxy data-container mypostgrescontainer will open port 5432 on your machine over localhost and forward all connections to the upstream data container in the Redgate Clone service.

This can be useful for environments where you've already got localhost connection strings configured and you don't want to manually update the port when data containers are created.

The proxy will run indefinitely until you cancel the command (e.g with CTRL+C).

Command

rgclone proxy data-container <ContainerNames_Or_ContainerIDs>

You can also optionally specify the local port to use:

rgclone proxy data-container <ContainerNames_Or_ContainerIDs> --port 9999

Note: For SQL Server the address for the proxied data container is 127.0.0.1 (not localhost). This is due to SQL Server treating localhost as a "shared memory" connection which is not supported by the proxy command.

completion

Generates a command-line autocompletion script and writes to stdout.

Bash

To load completions for each session, execute once:

Linux:

rgclone completion bash > /etc/bash_completion.d/rgclone

macOS:

rgclone completion bash > /usr/local/etc/bash_completion.d/rgclone

Zsh

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions for each session, execute once:

rgclone completion zsh > "${fpath[1]}/_rgclone"

You will need to start a new shell for this setup to take effect.

Fish

rgclone completion fish | source

To load completions for each session, execute once:

rgclone completion fish > ~/.config/fish/completions/rgclone.fish

version

Lists the client version of the local copy of rgclone, the version of the Web API it was built for and the latest versions of the Web API and rgclone available in the server at present time.

If the local client version of rgclone is different than the latest available one, a warning will be issued after running any command. Please see CLI Installation for more details.

Command 

> rgclone version
Current rgclone version                   : 0.1.0 (built for Web API version '1.0.29526')
Latest rgclone version (hosted in server) : 0.1.0
Current Web API version (hosted in server) : 1.0.29526