Codewind Command Line Interface (CLI)
Install Codewind on MacOS or Windows. Prebuilt binary files are available for download on Eclipse.
Table of Contents
- Before starting
- Downloading the release binary file for
- Building and deploying locally on MacOS
- Creating a cross-platform binary
- Running the Tests
- API
- Contributing
Before starting
Ensure that you are logged in to Docker. Type docker login
into a command line window and follow the instructions.
Downloading the release binary file for:
MacOS
- Download the release binary file to a folder on your system.
- Use the
cd
command to go to the location of the downloaded file in the command line window. - If the binary file has the
.dms
extension, remove the extension so that the file is namedcwctl-macos
. - Enter the
chmod +x cwctl-macos
command to give yourself execution permissions for the binary. - If you already have a
codewind-workspace
with your projects in it, copy it into your/Users/<username>
home directory. If you do not already have a workspace, the CLI creates an empty workspace for you in this directory. - Type
./cwctl-macos
in the command line window to run the CLI. - To run a command, enter
./cwctl-macos <command>
.
Linux
- Download the release binary file to a folder on your system.
- Use the
cd
command to go to the location of the downloaded file in the command line window. - If necessary, remove any file extensions so that the file is named
cwctl-linux
. - Enter the
chmod +x cwctl-linux
command to give yourself execution permissions for the binary. - If you already have a
codewind-workspace
with your projects in it, copy the workspace into your$HOME
home directory. If you do not already have a workspace, the CLI creates an empty workspace for you in this directory. - Install
docker-compose
with Install Docker Compose. - To run the CLI, enter
./cwctl-linux
in the command line window. - To run a command, enter
./cwctl-linux <command>
.
Windows
- Download the release binary file to a folder on your system.
- Use the
cd
command to go to the location of the downloaded file in the command prompt. - Ensure that the binary file has an
.exe
extension. If it doesn't, add the extension to the file name. - Ensure that your
C:\
drive is shared with Docker Desktop for Windows. To check, go to Settings>Shared drives and make sure theC:\
drive check box is selected. - If you already have a
codewind-workspace
with your projects in it, copy thecodewind-workspace
into yourC:\
directory. If you do not already have a workspace, the CLI creates an empty one for you in this directory. - To get started and see the commands that are available, type the
.\cwctl-win.exe
command in the command prompt. - To run a command, enter
.\cwctl-win.exe <command>
.
Building and deploying locally on MacOS
- Ensure that you have a Go environment set up. If you don't yet have a Go environment, see Install Go.
- Create the directory tree expected
~/go/src/github.com/eclipse
- Change to the eclipse directory:
cd ~/go/src/github.com/eclipse
- Clone the repository by typing
git clone https://github.com/eclipse/codewind-installer.git
- Set the environment variable:
export GO111MODULE=on
- Change to the project directory:
cd codewind-installer
- run
go mod tidy
- Change to the cli directory:
cd cmd/cli
- Build the binary and give it a name with the
go build -o <binary-name>
command. To build a binary without the debug symbols, use thego build -ldflags="-s -w" -o <binary-name>
command. - Copy your
codewind-workspace
into your/Users/<username>/
home directory. - Type
./<binary-name>
in the command line window to run the CLI. - To run a sub command, enter
./<binary-name> <command>
.
Creating a cross-platform binary
- Use the
go tool dist list
command to get a list of the possibleGOOS/ARCH
combinations available to build. - Choose the
GOOS/ARCH
that you want to build for and then enterGOOS=<OS> GOARCH=<ARCH> go build
to create the binary. To build a binary without the debug symbols, use theGOOS=<OS> GOARCH=<ARCH> go build -ldflags="-s -w"
command.
Running the Tests
Integration tests (Bats-core tests)
- Set up your environment by installing bats-core as per the bats-core instructions found at https://github.com/bats-core/bats-core.
- Clone the
codewind-installer
repository. - Use the
cd
command to go to the top level project directory. - Ensure your system environment is clean by having no Codewind images installed or containers running.
- To run the tests, enter the
bats integration.bats
command in the command line window and wait for the tests to finish.
Unit tests
All tests in current directory and all of its subdirectories
$ go test ./...
All tests from a package (e.g. utils)
$ go test github.com/eclipse/codewind-installer/utils
All tests from a package (e.g. utils) whose names match a regex
$ go test github.com/eclipse/codewind-installer/utils -run ^(TestDetermineProjectInfo)$ # or ^(DetermineProjectInfo)$
$ go test github.com/eclipse/codewind-installer/utils -run ^(TestDetermineProjectInfo)$
Notes
In VSCode, the UI and Command Palette provide easy ways to run specific packages and tests
go test
will just report that tests passed
If tests pass, E.g.:
PASS
ok github.com/eclipse/codewind-installer/utils
To see more details, use go test -v
.
Test coverage
$ ./test.sh -coverage
This is the same as go test ./...
, but outputs test coverage scores for each function, package, and an overall score.
API
CLI Commands
Command | Alias | Usage |
---|---|---|
project | 'Manage Codewind projects' | |
install | in |
'Pull pfe & performance images from dockerhub' |
start | 'Start the Codewind containers' | |
status | 'Print the installation status of Codewind' | |
stop | 'Stop the running Codewind containers' | |
stop-all | 'Stop all of the Codewind and project containers' | |
remove | rm |
'Remove Codewind and Project docker images' |
templates | 'Manage project templates' | |
version | 'Print the versions of Codewind containers, for a given connection' | |
sectoken | st |
'Authenticate with username and password to obtain an access_token' |
secrole | sl |
'Manage realm based ACCESS roles' |
secrealm | sr |
'Manage new or existing REALM configurations' |
secclient | sc |
'Manage new or existing APPLICATION access configurations' |
seckeyring | sk |
'Manage Codewind keys in the desktop keyring' |
secuser | su |
'Manage new or existing USER access configurations' |
connections | con |
'Manage connections configuration list' |
loglevels | log |
'Get or set logging levels for Codewind containers' |
registrysecrets | rs |
'Manage docker registry secrets' |
diagnostics | dg |
'Gathers logs and project files to aid diagnosis of Codewind errors' |
help | h |
'Shows a list of commands or help for one command' |
Command Options:
project
--url/-u <value>
- URL of project to download
Subcommands:
create
- Downloads a project created from a template, at the given URL
Flags: --url,-u value URL of project to download --path,-p value Path at which to create the new project --conid value Connection ID of PFE that will be used to validate the project (optional) --username value Username for GitHub account authorized to download the provided URL. Takes precedence over git credentials stored in keychain (optional) --password value Password for GitHub account authorized to download the provided URL. Takes precedence over git credentials stored in keychain (optional) --personalAccessToken value PersonalAccessToken authorized to download the provided URL. Takes precedence over git credentials stored in keychain (optional)
validate
- Returns the predicted language and build type for a project, and writes a default .cw-settings to it if one does not already exist
Flags: --path,-p value Project path, on local disk --type,-t value Project build type, if known (not required) --conid value Connection ID of PFE that will be used to validate the project (optional)
bind
- Bind a project to Codewind for building and running
Flags: --name,-n value Project name --language,-l value Project language --type,-t value Project Type --path,-p value Project Path --conid value Connection ID
sync
- Synchronize a bound project to its connection
Flags: --path,-p value Project Path --id,-i value Project ID --time,-t value UNIX timestamp of the last sync for the given project, in milliseconds
list
- List projects bound to a Codewind deployment
Flags --conid value Connection ID
get
- Get a single project, requires either the project ID or name
When using a project ID the CLI will automatically detect which connection it relates to
Flags --id value Project ID --name Project name --conid Connection ID
restart
- Restart a project
Flags --id, i Project ID --conid Connection ID --startMode "run" | "debug" | "debugNoInit"
install
--tag/-t <value>
- Dockerhub image tag (default: "latest")
--json/-j
- Specify terminal output
Subcommands:
remote
- Install a remote deployment of Codewind
Flags: --namespace,-n value Kubernetes namespace to install into --session,-ses value Codewind session secret to encrypt session store --ingress,-i value Ingress Domain eg: 10.22.33.44.nip.io --kadminuser,-au value Keycloak admin user --kadminpass,-ap value Keycloak admin password --kdevuser,-du value Keycloak developer username --kdevpass,-dp value Keycloak developer username initial password --krealm,-r value Keycloak realm to setup --kclient,-c value Keycloak client to setup --pvcsize,-p value Codewind PVC size (integer between 1 and 999 Gigabytes) --kurl value Don't deploy a new Keycloak pod, use an existing one at this URL --konly Install a deployment of Keycloak only
start
--tag/-t <value>
- Dockerhub image tag (default: "latest")
--debug/-d
- Add debug output
status
--json/-j
- Specify terminal output
stop
Note: No additional flags
diagnostics/dg
Note: No additional flags
Subcommands:
collect
- Gathers logs and project files to aid diagnosis of Codewind errors
Flags: --conid - Triggers diagnostics collection for the remote codewind connection ID (must have currently configured Kubectl connection)
--eclipseWorkspaceDir/-e - The location of your Eclipse workspace directory if using the Eclipse IDE
--intellijLogsDir/-i ` - The location of your IntelliJ logs directory if not using the IntelliJ IDE default location
--all/-a - Collects diagnostics for all defined connections, remote and local
--projects/-p - Collect project containers information
--nozip/-n - Does not create collection zip and leaves individual collected files in place
remove
- Removes the diagnostics directory and all its contents from the Codewind home directory
Note: No additional flags
stop-all
Note: No additional flags
remove
--tag/-t <value>
- Dockerhub image tag.
Note: Failing to specify a
--tag
, will result in an attempt to remove the defaultlatest
tagged Codewind images on the host machine.
Subcommands:
local/l
- Removes and deletes a Codewind local deployment
Flags: --tag - Docker hub image tag
remote/r
- Removes and deletes a Codewind remote deployment from Kubernetes
Flags: --namespace - Kubernetes namespace --workspace - Codewind workspace ID
keycloak/k
- Removes and deletes a Keycloak deployment from Kubernetes
Flags: --namespace - Kubernetes namespace --workspace - Keycloak workspace ID
templates
Note: No additional flags
Subcommands:
list/ls
- List available templates
repos
- Manage template repositories
Subcommands:
list/ls
- List available template repositories
add
- Add a new template repository
Flags: --url - URL to template repository index.json --name - Custom name for template repository --description - Custom description for template repository --username - GitHub username (required if accessing the provided URL requires GitHub authentication and you do not provide --personalAccessToken) --password - GitHub password (required if accessing the provided URL requires GitHub authentication and you do not provide --personalAccessToken) --personalAccessToken - GitHub personal access token (required if accessing the provided URL requires GitHub authentication and you do not provide --username and --password)
version
Flags: --conid value Connection ID (see the connections cmd) --all - Show Container versions for all Codewind connections
sectoken
Subcommands:
get/g
- Authenticate and obtain an access_token.
Note 1:: The preferred way to authenticate is by supplying just the connection ID (conid) and username. In this mode the command will use the stored password from the platform keyring Note 2:: If you dont have a connection ID (conid) you must supply use the host, realm and client flags Note 3:: You can use a combination of both the connection ID (conid) and host/realm/client flags. In this mode, the host/realm/client flags take precedence override the connection defaults Note 4:: The password flag is optional when used with the connection ID (conid) flag and when a password already exists in the platform keyring. Including the password flag will update the keychain password after a successful login or add a password to the keychain if one does not exist
Flags: --host value URL or ingress to Keycloak service --realm value Application realm --username value Account Username --password value Account Password --client value Client --conid value Connection ID (see the connections cmd)
sectoken
Subcommands:
refresh/r
- Refresh access_token using cached refresh_token
Refresh tokens are automatically stored in the platform keychain. This command will use the refresh token to obtain a new access token from the authentication service. The access_token can then be used by curl or socket connections when accessing Codewind.
Flags: --conid value Connection ID (see the connections cmd)
secrealm
Subcommands:
create/c
- Create a new realm (requires either admin_token or username/password)
Flags: --host value URL or ingress to Keycloak service --newrealm value Application realm to be created --accesstoken value Admin access_token
secclient
Subcommands:
create/c
- Create a new client in an existing Keycloak realm (requires either admin_token or username/password)
--host value URL or ingress to Keycloak service --realm value Application realm where client should be created --newclient value New client ID to create --redirect value Allowed redirect callback URL eg:
http://127.0.0.1:9090/*
--accesstoken value Admin access_token
get/g
- Get client id (requires either admin_token or username/password)
--host value URL or ingress to Keycloak service --realm value Application realm --clientid value Client ID to retrieve --accesstoken value Admin access_token --username value Admin Username --password value Admin Password
secret/s
- Get client secret (requires either admin_token or username/password)
--host value URL or ingress to Keycloak service --realm value Application realm --clientid value Client ID to retrieve --accesstoken value Admin access_token --username value Admin Username --password value Admin Password
seckeyring
Subcommands:
update/u
- Add new or update existing Codewind credentials key in keyring
--conid
<value>
Connection ID (see the connections cmd) --username<value>
Username --password<value>
Password
validate/v
- Checks if credentials key exist in the keyring
--conid
<value>
Connection ID (see the connections cmd) --username<value>
Username
secuser
Subcommands:
create/c
- Create a new user in an existing Keycloak realm (requires either admin_token or username/password)
--host value URL or ingress to Keycloak service --realm value Application realm --accesstoken value Admin access_token --username value Admin Username --password value Admin Password --name value Username to add
get/g
- Gets an existing Keycloak user from an existing realm (requires either admin_token or username/password)
--host value URL or ingress to Keycloak service --realm value Application realm --accesstoken value Admin access_token --username value Admin Username --password value Admin Password --name value Username to query
setpw/p
- Reset an existing users password (requires either admin_token or username/password)
--host value URL or ingress to Keycloak service --realm value Application realm --accesstoken value Admin access_token --username value Admin Username --password value Admin Password --name value Username to query --newpw value New replacement password
addrole/p
- Adds an existing role to a user (requires either admin_token or username/password)
--host value URL or ingress to Keycloak service --realm value Application realm --accesstoken value Admin access_token --name value Username to target --role value Name of an existing role to add
connections
Subcommands:
add/a
- Add a new connection to the list
Flags: --label value A displayable name --url value The ingress URL of the PFE instance
update/u
- Update an existing connection
Flags: --conid value The Connection ID to update --label value A displayable name --url value The ingress URL of the PFE instance
get/g
- Get a connection using its ID
Flags: --conid value The Connection ID to retrieve
remove/rm
- Remove a connection from the list
Flags: --conid value A Connection ID
list/ls
- List known connections
Note: No additional flags
reset
- Resets the connections list to a single local connection
Note: No additional flags
loglevels
Flags: --conid value The Connection ID of the remote Codewind installation. Defaults to
local
.
Arguments: The log level to set, one of
error
,warn
,info
,debug
,trace
remote
Subcommands:
list/l
- List all remote deployments of Codewind
Flags: --namespace value The namespace to check (defaults to all)
registrysecrets
Subcommands:
add/a
- Add a new docker registry secret and return the updated list of secrets
Flags: --conid value Connection ID (see the connections cmd). Defaults to
local
. --address value The address of the docker registry --username value The username for the docker registry --password value The password for the docker registry --locallogin=[true|false] Whether to perform a local docker login to the registry. Defaults to true.
list/ls
- List the docker secrets (registries and usernames)
Flags: --conid value Connection ID (see the connections cmd). Defaults to
local
.
remove/rm
- Remove a docker registry secret and return the updated list of secrets
Flags: --conid value Connection ID (see the connections cmd). Defaults to
local
. --address value The address of the docker registry to remove
help
--help/-h
- Shows a list of commands or help for one command
Contributing
Submit issues and contributions: