From 5e4361579653a035b254aea35f8e1e7545c46d50 Mon Sep 17 00:00:00 2001 From: Steven Schattenberg Date: Wed, 9 Apr 2025 10:43:04 -0500 Subject: [PATCH 1/3] copy edits of comments and docs --- Makefile | 10 +-- cmd/commands.go | 2 +- cmd/root.go | 2 +- docs/commands-quick-reference.md | 4 +- docs/configuration-reference.md | 115 +++++++++++++++--------------- docs/index.md | 1 - docs/running-from-source.md | 16 ++--- docs/working-with-repositories.md | 15 ++-- 8 files changed, 78 insertions(+), 87 deletions(-) diff --git a/Makefile b/Makefile index 747dd340..466f94ae 100644 --- a/Makefile +++ b/Makefile @@ -16,7 +16,7 @@ export CGO_ENABLED := 0 coverage \ licenses \ snapshot \ - test + test # The help target displays a help message that includes the avialable targets # in this `Makefile`. It is the default target if `make` is run without any @@ -33,9 +33,9 @@ help: @echo " test - Run test suite" @echo "" -# The config target shows the current configured values that are enforce when +# The config target shows the current configured values that are enforced when # any `make` target is run. -config: +config: @echo "GOOS=${GOOS}" @echo "GOARCH=${GOARCH}" @echo "CGO_ENABLED=${CGO_ENABLED}" @@ -54,7 +54,7 @@ coverage: @scripts/test.sh coverage # The licenses target is used to make sure that all source code files have the -# appropriate license header in them. It will also generate a license file +# appropriate license header in them. It will also generate a license file # that includes all of the applicable licenses for any 3rd party libraries that # have been included in this project. To use this target, you must have the # `go-licenses` tool installed and available in your path. See @@ -84,7 +84,7 @@ build: install -o bin/ipctl \ -ldflags="-X 'github.com/itential/ipctl/internal/metadata.Build=$$(git rev-parse --short HEAD)' -X 'github.com/itential/ipctl/internal/metadata.Version=$$(git tag | sort -V | tail -1)'" -# The test target runs the unit tests for this project. All unit tests are +# The test target runs the unit tests for this project. All unit tests are # based on mock data for the various services it connects to. The target # should run without error before making any pull requests to this project. test: diff --git a/cmd/commands.go b/cmd/commands.go index 7ba4e0db..6e3074d8 100644 --- a/cmd/commands.go +++ b/cmd/commands.go @@ -132,7 +132,7 @@ func platformCommands(r handlers.Runtime, id string) []*cobra.Command { }) } -// dataserCommands provide a set of commands for performing batch operations on +// datasetCommands provide a set of commands for performing batch operations on // specific asset types func datasetCommands(r handlers.Runtime, id string) []*cobra.Command { h := handlers.NewHandler(r) diff --git a/cmd/root.go b/cmd/root.go index 1e1be98e..f795f9e0 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -38,7 +38,7 @@ func loadCommands(cmd *cobra.Command, runtime handlers.Runtime) { addRootCommand(cmd, runtime, "Plugin Commands:", pluginCommands) } -// versionCommand is a top level command that display's the current application +// versionCommand is a top level command that displays the current application // version. func versionCommand() *cobra.Command { var cmd = &cobra.Command{ diff --git a/docs/commands-quick-reference.md b/docs/commands-quick-reference.md index d5df110b..93caca9d 100644 --- a/docs/commands-quick-reference.md +++ b/docs/commands-quick-reference.md @@ -1,7 +1,7 @@ # Command Table -The table below provides a quick reference for that shows which commands are -support for which assets. +The table below provides a quick reference that shows which commands are +supported for which assets. | Asset | get | describe | create | delete | copy | clear | import | export | |------------------------------------|-----|----------|--------|--------|------|-------|--------|--------| diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md index 78a02c05..b417b2d9 100644 --- a/docs/configuration-reference.md +++ b/docs/configuration-reference.md @@ -1,7 +1,7 @@ -# Configuration Reference. +# Configuration Reference This document provides details about the available configuration options -available to configure `ipctl`. All configuration options can be specified +available to configure `ipctl`. All configuration options can be specified either in a configuration file and/or as environment variables. Values configured using environment variables take precedence over the same @@ -21,10 +21,10 @@ one or more key=value settings that can be used to configure the application. ## Avoiding security risks The `ipctl` configuration file may contain senstive configuration values used -to authenticate to services. The configuration file should be secured such +to authenticate to services. The configuration file should be secured such that only the current user has access to the configuration directory and file. -The following example commands would security the directory and file when +The following example commands would secure the directory and file when running `ipctl` from a Linux host. ```bash @@ -36,20 +36,20 @@ Please consult your OS documentation for specific commands. ## Using profiles -The application configuration flie supports configuring multiple profiles A -profile defines the connection settings for a given server. When `iapctl` +The application configuration file supports configuring multiple profiles. A +profile defines the connection settings for a given server. When `ipctl` attempts to conect to a server, it will look up the profile settings in the conifguraiton file based on the profile name. The profile name can be passed to any command using the `--profile ` command line argument. A default profile can also be set in the configuration file. See `default_profile` in the [Applicaiton Settings}(#Application -Settings) section for a descrption. +Settings) section for a description. ## Configuration options The entries below provide the set of available configuration options that can -be used with`ipctl`. +be used with `ipctl`. ### Application Settings @@ -57,23 +57,23 @@ The `application` settings can be used to configure application level settings for `ipctl`. The following values are configurable within `[application]`. All values in this section can be overridden with environment variables. -For instance to override the `default_profile` value, the environment variable -would be `IPCTL_APPLICATION_DEFAULT_PROFILE` +For instance, to override the `default_profile` value, the environment variable +would be `IPCTL_APPLICATION_DEFAULT_PROFILE`. #### `default_profile` Configures the name of the profile to use if not explicitly set using the -command line option `--profile` +command line option `--profile`. -The default value for `default_profile` is `null` +The default value for `default_profile` is `null`. #### working_dir -Configures the working directory for the application. The working directory +Configures the working directory for the application. The working directory is the default directory where the application will look for the configuration file. -The default value for `working_dir` is `~/.platform.d` +The default value for `working_dir` is `~/.platform.d`. ### Log Settings @@ -85,11 +85,11 @@ where `` is the key name. #### level -Configures the level of detail sent to the logging facility. This -configuration value accepts one of the following values: `INFO`, `DEBUG`, -`TRACE`. +Configures the level of detail sent to the logging facility. This +configuration value accepts one of the following values: `info`, `debug`, +`trace`. -The default value for `level` is `info` +The default value for `level` is `info`. #### file_json @@ -102,9 +102,9 @@ The default value for `level` is `info` ### Terminal Settings The terminal settings section provides configuration values for managing the -terminal environment. All configuration settings are maintained under the +terminal environment. All configuration settings are maintained under the `[terminal]` section and can be overridded using environment variables -prefaced with `IPCTL_TERMINAL_` +prefaced with `IPCTL_TERMINAL_`. #### no_color @@ -114,7 +114,7 @@ is `false`, the output may use color in the output. This configuration value only applies to `human` output. -The default value for `no_color` is `false` +The default value for `no_color` is `false`. #### default_output @@ -122,9 +122,9 @@ Sets the default output format for commands. Currently, the application supports three output formats `human`,`json` and `yaml`. Use this configuration to define the default output format for all commands. -This setting can be override for any command using `--output ` +This setting can be override for any command using `--output `. -The default value for `default_output` is `human` +The default value for `default_output` is `human`. #### pager @@ -132,7 +132,7 @@ Enables or disables the pager feature in the application. The pager feature will pass the returned output through `less`, which must be available on your system, to paginate the output. -The default value for `pager` is `true` +The default value for `pager` is `true`. #### timestamp_timezone @@ -140,11 +140,11 @@ Configures the timezone to use when converting log timestamp messages from the application. This setting can be used to automatiocally translate the log messages to any desired timezone. -The default value for `timestamp_timezone` is `utc` +The default value for `timestamp_timezone` is `utc`. ### Git settings -Whenw working with git repositories, there are some global settings that should +When working with git repositories, there are some global settings that should be configured. This section provides a configuration settings for setting global git options. @@ -153,14 +153,14 @@ global git options. Configures the name to use when making commits using git. The name configured here will be displayed in the commit message. -The default value for `name` is `null` +The default value for `name` is `null`. #### `email` Configures the email address to use when making git commits. The email address will be used in commit messages. -The default value for `email` is `null` +The default value for `email` is `null`. #### `user` @@ -173,7 +173,7 @@ The default value for `user` is `git`. ### Profiles Profiles provide server specific configuration settings for working with -Itential Platform servers. The configuration file format suppors creating one +Itential Platform servers. The configuration file format supports creating one or more named profiles. To create a named profile, start the section with `[profile ]`. For @@ -192,13 +192,13 @@ accomplished by setting `IPCTL_PROFILE__PASSWORD` to the desired value. For instance, to set the password for a profile callend `prod`, the environment variable would be `IPCTL_PROFILE_PROD_PASSWORD`. The value would override any -value in the connfiguration file. +value in the configuration file. #### `host` Sets the hostname or IP address of the Itential Platform server to connect to. -The default value for `host` is `localhost` +The default value for `host` is `localhost`. #### `port` @@ -215,11 +215,10 @@ The default value for `port` is `0`. Enables or disables the use of TLS for the connecton. When this value is set to `true`, the application will attempt to establish a TLS connecton to the -server. When this value is set to `false` the application will not attempt to +server. When this value is set to `false` the application will not attempt to use TLS when connecting to the server. -The default value for `use_tls` is `true` - +The default value for `use_tls` is `true`. #### `verify` @@ -228,30 +227,30 @@ this value is set to `true`, certificates received from the server are validated. When this value is set to `false`, certifcates are assumed valid. This feature is useful when using self-signed certificates for TLS connections. -The default value for `verify` is `true` +The default value for `verify` is `true`. #### `username` -Cnfigures the name of the user to use when authenticating to the Itential +Configures the name of the user to use when authenticating to the Itential Platform server. This should be the username used to login to the server and determines the level of authorzation. -The default value for `username` is `admin@pronghorn` +The default value for `username` is `admin@pronghorn`. #### `password` Configures the password to use when authenticating the connection to Itential Platform server. -The default value for `password` is `admin` +The default value for `password` is `admin`. #### client_id Sets the client identifier for working with Itential Platform running in the -cloud at itential.io. The client id can be obtained when creating a service -acoount in Itential Cloud +cloud at itential.io. The client id can be obtained when creating a service +account in Itential Cloud. -The default vlaue for `client_id` is `null` +The default value for `client_id` is `null`. #### client_secret @@ -259,33 +258,32 @@ Configures the client secret for working with Iential Platform running in Itential Cloud. The client secret can be obtained when creating a service account in Itential Cloud. -The default value for `client_secret` is `null` +The default value for `client_secret` is `null`. #### timeout Configure the timeout value in seconds for request messages sent to the server. -The default value for `timeout` is `5` +The default value for `timeout` is `5`. #### mongo_url Configures the URL to use to make calls directly to the Mongo database. This is primarily used by plugins. -The default value for `mongo_url` is `null` - +The default value for `mongo_url` is `null`. ### Repository settings Repositories allow for the configuration of named repository configurations for -working with the `push` and `pull` commands. The configuration file supports +working with the `push` and `pull` commands. The configuration file supports creating one or more repository configuration entries in the configuration file. Repository configurations are sections prefixed with `repository`. For instance, to create a repository named `assets`, the section would be -`[repository assets]`. Once configured, the repository can be referenced by +`[repository assets]`. Once configured, the repository can be referenced by name in various commands. Any configuration value included in the `repository` section can be overridden @@ -294,55 +292,54 @@ instance, to override the `reference` configuration value for the repository named `assets`, the environment variable would be `IPCTL_REPOSITORY_ASSETS_REFERENCE`. - #### url Provides the full URL to the git repository to use for this named repository -object. This cofniguration setting accepts any valid git URL format including: +object. This configuration setting accepts any valid git URL format including: - SSH Transport URLs - Git Transport URLs - HTTP/S Transport URLs - Local Transport URLs -The default value for `url` is `null` +The default value for `url` is `null`. #### private_key Configures the private key to use when authenticating to the git repository -over SSH. This value contains the actual private key. +over SSH. This value contains the actual private key. -Note: This configuration setting is mutually exclusive with `private_key_file` +Note: This configuration setting is mutually exclusive with `private_key_file`. -The default value for `private_key` is `null` +The default value for `private_key` is `null`. #### private_key_file -Conifgures the path to the file containing the private key to use when +Configures the path to the file containing the private key to use when authenticating to the repository over SSH. Note: This configuration setting is mutually exclusive with `private_key`. -The default value for `private_key_file` is `null` +The default value for `private_key_file` is `null`. #### reference Configures the git reference to use with this named repository. The git -reference can be a git branch, tag or specific SHA. If this value is not +reference can be a git branch, tag or specific SHA. If this value is not configured, the default branch configured on the server will be used. -The default value for `reference` is `null` +The default value for `reference` is `null`. #### name Configures the name to be included in commit messages when using the `push` command. -The default value for `name` is `null` +The default value for `name` is `null`. #### email Configures the email address to include in commit messages created when using the `push` command. -The default value for `email` is `null` +The default value for `email` is `null`. diff --git a/docs/index.md b/docs/index.md index e197b014..9b9d0b81 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,4 +8,3 @@ The `ipctl` project provides a command line interface for working with Itential - [Running from source](running-from-source.md) - [Command Quick Reference](commands-quick-reference.md) - [Configuration Reference](configuration-reference.md) - diff --git a/docs/running-from-source.md b/docs/running-from-source.md index 82afae4c..75f6d423 100644 --- a/docs/running-from-source.md +++ b/docs/running-from-source.md @@ -1,8 +1,8 @@ -# Running from source +# Running ipctl -The `ipctl` application can be direclty run from a git checkout. In order to +The `ipctl` application can be directly run from a git checkout. In order to run the application directly from the source tree, you must have `golang` -installed and available on in your local environment. +installed and available on your local environment. To get started, first install `golang` 1.22 on your local system. Installation instruction can be found [here](https://go.dev/doc/install). @@ -13,24 +13,24 @@ The repository includes a `Makefile` with targets to allow installing and building the application. Be sure to install `make` into your local environment as well. -Once installed and from the root directory where you have cloned the -repository, and run `make install`. This will install of the `golang` +Once installed, go to the root directory where you have cloned the +repository, and run `make install`. This will install all of the `golang` dependencies and prepare your system to run the code from source. -Finally to execute the code from source run `go run main.go` which will run +Finally, to execute the code from source run `go run main.go` which will run the application directly from source code. ## Building the executable You can also build the application executable using the `build` make target. To build the application simply run `make build` from the root folder of the -repository. This will build the executable and place it into the `bin/` +repository. This will build the executable and place it into the `bin/` folder. ## Building snapshots Finally, the `Makefile` also supports building snapshots. Snapshots will build -the binary for all supported platforms. To create a snapshot build, you will +the binary for all supported platforms. To create a snapshot build, you will need to have `goreleaser` installed and available in your local environment. See [here](https://goreleaser.com/) for details on how to install `goreleaser`. diff --git a/docs/working-with-repositories.md b/docs/working-with-repositories.md index 64d8d598..95268ad7 100644 --- a/docs/working-with-repositories.md +++ b/docs/working-with-repositories.md @@ -1,7 +1,7 @@ # Working with repositories One of the key features of `ipctl` is the opportunity to work natively with -`git` repositories. This integration allows you to directly push and pull +`git` repositories. This integration allows you to directly push and pull Itential Platform assets to and from git repositories using the `import` and `export` commands with command line options. @@ -98,7 +98,7 @@ push it into a Git repository. The file will be stored in the root of the repository. In some cases, it may be desirable to store the file in a specific folder -within the repository. In order to do that, use the `--path` command line +within the repository. In order to do that, use the `--path` command line option. For example, assume the same project as before needs to be stored in folder @@ -117,8 +117,8 @@ path does not exist in the repository, it will be created. ## Pulling assets from repositories using `import` The `import` command can be used to pull an asset directly from a Git -repository and import it into an Itential Platform server. The `import` -command accepts the following command line options for performing this task. +repository and import it into an Itential Platform server. The `import` +command accepts the following command line options for performing this task: - `--repository` - `--reference` @@ -132,7 +132,7 @@ directly from a Git repository. ```bash ipctl import project "My Test Project.project.json" \ - --repository git@github.com:itential/assets.git \ + --repository git@github.com:itential/assets.git ``` When run, the command will connect to the Git repository defined by @@ -148,8 +148,3 @@ repository. ipctl import project "test/projects/My Test Project.project.json" \ --repository git@github.com:itential/assets.git ``` - - - - - From 1d4eb64ce41bef01011e2810c07e6fa737f47fdb Mon Sep 17 00:00:00 2001 From: Steven Schattenberg Date: Thu, 10 Apr 2025 08:38:08 -0500 Subject: [PATCH 2/3] More copy edits --- internal/flags/jsonforms.go | 2 +- internal/flags/localaaa.go | 2 +- internal/flags/roles.go | 2 +- internal/flags/templates.go | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/internal/flags/jsonforms.go b/internal/flags/jsonforms.go index 49ff4604..c055c79b 100644 --- a/internal/flags/jsonforms.go +++ b/internal/flags/jsonforms.go @@ -15,7 +15,7 @@ type JsonFormCreateOptions struct { func (o *JsonFormCreateOptions) Flags(cmd *cobra.Command) { cmd.Flags().StringVar(&o.Description, "description", o.Description, "Description of JSON form") - cmd.Flags().BoolVar(&o.Replace, "replace", o.Replace, "Replace the exist form if it exists") + cmd.Flags().BoolVar(&o.Replace, "replace", o.Replace, "Replace the existing form if it exists") } type JsonFormGetOptions struct { diff --git a/internal/flags/localaaa.go b/internal/flags/localaaa.go index fb9c9ee8..c77737f3 100644 --- a/internal/flags/localaaa.go +++ b/internal/flags/localaaa.go @@ -13,5 +13,5 @@ type LocalAAAOptions struct { } func (o *LocalAAAOptions) Flags(cmd *cobra.Command) { - cmd.Flags().StringArrayVar(&o.Groups, "group", o.Groups, "Group to insert user into") + cmd.Flags().StringArrayVar(&o.Groups, "group", o.Groups, "Group to insert the user into") } diff --git a/internal/flags/roles.go b/internal/flags/roles.go index 9db7f7d0..c2ff3c6e 100644 --- a/internal/flags/roles.go +++ b/internal/flags/roles.go @@ -26,7 +26,7 @@ type RoleGetOptions struct { } func (o *RoleGetOptions) Flags(cmd *cobra.Command) { - cmd.Flags().BoolVar(&o.All, "all", o.All, "Display all roles including buitin roles") + cmd.Flags().BoolVar(&o.All, "all", o.All, "Display all roles including builtin roles") cmd.Flags().StringVar(&o.Type, "type", o.Type, "Display only roles of a certain type") } diff --git a/internal/flags/templates.go b/internal/flags/templates.go index 71ccf8b3..8598b9ad 100644 --- a/internal/flags/templates.go +++ b/internal/flags/templates.go @@ -16,8 +16,8 @@ type TemplateCreateOptions struct { } func (o *TemplateCreateOptions) Flags(cmd *cobra.Command) { - cmd.Flags().StringVar(&o.Description, "description", o.Description, "Description of JSON form") - cmd.Flags().BoolVar(&o.Replace, "replace", o.Replace, "Replace the exist form if it exists") + cmd.Flags().StringVar(&o.Description, "description", o.Description, "Description of template") + cmd.Flags().BoolVar(&o.Replace, "replace", o.Replace, "Replace the existing template if it exists") cmd.Flags().StringVar(&o.Group, "group", o.Group, "Group name (REQUIRED)") cmd.MarkFlagRequired("group") cmd.Flags().StringVar(&o.Type, "type", o.Type, "Type of template to create (REQUIRED)") From 3163c58cd771619de4f3ef5895e5a9374f990d7b Mon Sep 17 00:00:00 2001 From: Steven Schattenberg Date: Thu, 10 Apr 2025 10:11:27 -0500 Subject: [PATCH 3/3] Spelling and grammar check of none code files --- README.md | 11 +++-- docs/configuration-reference.md | 28 ++++++------ docs/running-from-source.md | 2 +- .../handlers/descriptors/adapter_models.yaml | 4 +- internal/handlers/descriptors/datasets.yaml | 6 +-- .../descriptors/integration_models.yaml | 2 +- .../handlers/descriptors/integrations.yaml | 4 +- internal/handlers/descriptors/jsonforms.yaml | 6 +-- internal/handlers/descriptors/models.yaml | 14 +++--- internal/handlers/descriptors/profiles.yaml | 4 +- internal/handlers/descriptors/projects.yaml | 44 +++++++++---------- internal/handlers/descriptors/roles.yaml | 26 +++++------ internal/handlers/descriptors/roletypes.yaml | 2 +- internal/handlers/descriptors/templates.yaml | 7 ++- internal/handlers/descriptors/workflows.yaml | 42 +++++++++--------- 15 files changed, 103 insertions(+), 99 deletions(-) diff --git a/README.md b/README.md index c755b07f..58ba49c9 100644 --- a/README.md +++ b/README.md @@ -9,14 +9,14 @@ guide you through getting up and running. ### Install `ipctl` -To install `ipctl` navigate to the [releases page](https://github.com/itential/ipctl/releases) and download the tarball that matches your machine OS and architecture. Then untar the compressed file put the `ipctl` executable in your path. +To install `ipctl` navigate to the [releases page](https://github.com/itential/ipctl/releases) and download the tarball that matches your machine OS and architecture. Then untar the compressed file put the `ipctl` executable in your path. ### Configuring `ipctl` The default configuration file for `ipctl` is `~/.platform.d/config`. This file is read by `ipctl` and used to configure various options. The configuration file is divided into multiple sections, each section providing one or more -key=vlaue configuration entries. +key=value configuration entries. The configuration file can be configured using any standard text editor and should be secured such that it is only readable by the currently logged in @@ -26,19 +26,18 @@ The `ipctl` application can also be configured using environment variables. If configured, environment variables take precedence over values set in the configuration file. -The configuration file uses profiles to define one or more target instances of Itential Platform. For example, the following will create a new profile called `devel` in the configuration file. +The configuration file uses profiles to define one or more target instances of Itential Platform. For example, the following will create a new profile called `devel` in the configuration file. -``` +```ini [profile devel] host = devel.itential.com ``` Once created, use the profile name when running commands. -``` +```bash ipctl export project test --profile devel ``` For a complete list of all configuration parameters, please see the configuration reference [here](docs/configuration-reference.md) - diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md index b417b2d9..d1c13b9d 100644 --- a/docs/configuration-reference.md +++ b/docs/configuration-reference.md @@ -8,19 +8,19 @@ Values configured using environment variables take precedence over the same values configured in a configuration file. By default, `ipctl` will load the configuration file `~/.platform.d/config`. -To use a different configuraiton file name and/or location, use the `--config` +To use a different configuration file name and/or location, use the `--config` command line option and pass it the path to the configuration file you wish to use. The configuration file can also be specified using the `IPCTL_CONFIG_FILE` environment variable. -The configuration file is organzied into sections with each section providing +The configuration file is organized into sections with each section providing one or more key=value settings that can be used to configure the application. ## Avoiding security risks -The `ipctl` configuration file may contain senstive configuration values used +The `ipctl` configuration file may contain sensitive configuration values used to authenticate to services. The configuration file should be secured such that only the current user has access to the configuration directory and file. @@ -38,12 +38,12 @@ Please consult your OS documentation for specific commands. The application configuration file supports configuring multiple profiles. A profile defines the connection settings for a given server. When `ipctl` -attempts to conect to a server, it will look up the profile settings in the -conifguraiton file based on the profile name. +attempts to connect to a server, it will look up the profile settings in the +configuration file based on the profile name. The profile name can be passed to any command using the `--profile ` command line argument. A default profile can also be set in the configuration -file. See `default_profile` in the [Applicaiton Settings}(#Application +file. See `default_profile` in the [Application Settings}(#Application Settings) section for a description. ## Configuration options @@ -103,7 +103,7 @@ The default value for `level` is `info`. The terminal settings section provides configuration values for managing the terminal environment. All configuration settings are maintained under the -`[terminal]` section and can be overridded using environment variables +`[terminal]` section and can be overridden using environment variables prefaced with `IPCTL_TERMINAL_`. #### no_color @@ -137,7 +137,7 @@ The default value for `pager` is `true`. #### timestamp_timezone Configures the timezone to use when converting log timestamp messages from the -application. This setting can be used to automatiocally translate the log +application. This setting can be used to automatically translate the log messages to any desired timezone. The default value for `timestamp_timezone` is `utc`. @@ -190,7 +190,7 @@ instance, assume we want to pass the password in using an environment variable instead of storing the password in the configuration file. This could be accomplished by setting `IPCTL_PROFILE__PASSWORD` to the desired value. -For instance, to set the password for a profile callend `prod`, the environment +For instance, to set the password for a profile called `prod`, the environment variable would be `IPCTL_PROFILE_PROD_PASSWORD`. The value would override any value in the configuration file. @@ -213,8 +213,8 @@ The default value for `port` is `0`. #### `use_tls` -Enables or disables the use of TLS for the connecton. When this value is set -to `true`, the application will attempt to establish a TLS connecton to the +Enables or disables the use of TLS for the connection. When this value is set +to `true`, the application will attempt to establish a TLS connection to the server. When this value is set to `false` the application will not attempt to use TLS when connecting to the server. @@ -224,7 +224,7 @@ The default value for `use_tls` is `true`. Enables or disables certificate validation for TLS based connections. When this value is set to `true`, certificates received from the server are -validated. When this value is set to `false`, certifcates are assumed valid. +validated. When this value is set to `false`, certificates are assumed valid. This feature is useful when using self-signed certificates for TLS connections. The default value for `verify` is `true`. @@ -233,7 +233,7 @@ The default value for `verify` is `true`. Configures the name of the user to use when authenticating to the Itential Platform server. This should be the username used to login to the server and -determines the level of authorzation. +determines the level of authorization. The default value for `username` is `admin@pronghorn`. @@ -254,7 +254,7 @@ The default value for `client_id` is `null`. #### client_secret -Configures the client secret for working with Iential Platform running in +Configures the client secret for working with Itential Platform running in Itential Cloud. The client secret can be obtained when creating a service account in Itential Cloud. diff --git a/docs/running-from-source.md b/docs/running-from-source.md index 75f6d423..483cb494 100644 --- a/docs/running-from-source.md +++ b/docs/running-from-source.md @@ -35,5 +35,5 @@ need to have `goreleaser` installed and available in your local environment. See [here](https://goreleaser.com/) for details on how to install `goreleaser`. Once `goreleaser` is installed, you can build your own snapshot using `make -snapshot` The comand will build the application for all supported platforms +snapshot` The command will build the application for all supported platforms and place them into the `dist/` folder. diff --git a/internal/handlers/descriptors/adapter_models.yaml b/internal/handlers/descriptors/adapter_models.yaml index 371eecbd..bc691772 100644 --- a/internal/handlers/descriptors/adapter_models.yaml +++ b/internal/handlers/descriptors/adapter_models.yaml @@ -7,11 +7,11 @@ get: group: admin-essentials description: | - Display one or more available adapter models + Display one or more available adapter models. The `get adapter-models` command will return the list of adapter models that are available on the server. example: | # Display list of adapter models - 4 ipctl get adapter-models + $ ipctl get adapter-models diff --git a/internal/handlers/descriptors/datasets.yaml b/internal/handlers/descriptors/datasets.yaml index aae1bd2c..29753202 100644 --- a/internal/handlers/descriptors/datasets.yaml +++ b/internal/handlers/descriptors/datasets.yaml @@ -10,10 +10,10 @@ load: dump: use: dump description: | - Dump a dataset + Dump a dataset. - The dataset dump command will connect to the running instance of Platform - and dump all of the configred assests into the specified path. + The dataset dump command will connect to the running instance of the Itential + Platform and dump all of the configured assets into the specified path. example: | # Dump all assets to `assets` diff --git a/internal/handlers/descriptors/integration_models.yaml b/internal/handlers/descriptors/integration_models.yaml index 2b5c139c..bc256aca 100644 --- a/internal/handlers/descriptors/integration_models.yaml +++ b/internal/handlers/descriptors/integration_models.yaml @@ -9,7 +9,7 @@ get: description: | Display one or more integration-models - The `get integraion-models` will display the list of integration models + The `get integration-models` will display the list of integration models that have been added to the server. describe: diff --git a/internal/handlers/descriptors/integrations.yaml b/internal/handlers/descriptors/integrations.yaml index 34b41de1..9fca4ce7 100644 --- a/internal/handlers/descriptors/integrations.yaml +++ b/internal/handlers/descriptors/integrations.yaml @@ -9,7 +9,7 @@ get: description: | Display one or more integrations - The `get integraions` will display the list of integration models + The `get integrations` will display the list of integration models that have been added to the server. The default output will display the list of the configured integrations and models. @@ -36,7 +36,7 @@ create: on the server (regardless of the model type), this command will return an error - When creating a new integraiton, the `--model` argument is required and + When creating a new integration, the `--model` argument is required and must reference an Integration Model already on the server. To see a list of available Integration Models, use the `get integration-models` command. diff --git a/internal/handlers/descriptors/jsonforms.yaml b/internal/handlers/descriptors/jsonforms.yaml index 33e47d70..9ecbebb4 100644 --- a/internal/handlers/descriptors/jsonforms.yaml +++ b/internal/handlers/descriptors/jsonforms.yaml @@ -9,7 +9,7 @@ get: description: | Display one or more jsonforms - The `get jsonforms` command will retreive all of the configured JSON + The `get jsonforms` command will retrieve all of the configured JSON forms from the instance of Platform and display them. When the output is set to `human` (default) this command will display the results in table format. @@ -70,7 +70,7 @@ delete: description: | Delete a jsonform - The delete command will delete the specifie jsonform from the instance + The delete command will delete the specified jsonform from the instance of Itential Platform. This is a destructive operation and cannot be recovered. If the specified jsonform does not exist on the server, this command will return an error. @@ -138,7 +138,7 @@ export: Export a jsonform Use the `export jsonform ` command to export a jsonform from the - server in JSON format. The exported asset can be immported into the same + server in JSON format. The exported asset can be imported into the same or another server. If specified jsonform does not exist, an error is returned. diff --git a/internal/handlers/descriptors/models.yaml b/internal/handlers/descriptors/models.yaml index f930c578..de1504c8 100644 --- a/internal/handlers/descriptors/models.yaml +++ b/internal/handlers/descriptors/models.yaml @@ -7,7 +7,7 @@ get: group: lifecycle-manager description: | - Dispaly one or more models + Display one or more models The `get models` command will retrieve all configured resource models from the server and display them in table format by default. @@ -36,8 +36,8 @@ delete: description: | Delete a model - The delete command will atempt to delete the resource model from the - specified server. In order to delete a model successfully, the model + The delete command will attempt to delete the resource model from the + specified server. In order to delete a model successfully, the model cannot have any current instances. If the model has any current instances, the command will return an @@ -84,8 +84,8 @@ import: required argument `path` which specifies the path to the file where the exported model resides. - Models can be imported direclty from Git repositories using the ``--repository` - otional argument. + Models can be imported directly from Git repositories using the ``--repository` + optional argument. example: | # Import a resource model from a file @@ -100,11 +100,11 @@ export: Export resource model The `export model` command will export a resource model from the Itential - Platform server. If exported model will be written to a file. If the + Platform server. If exported model will be written to a file. If the model name specified by the `name` argument does not exist, this command will return an error. - exmaple: | + example: | # Export a resource model called `CLI Test` $ ipctl export model "CLI Test" diff --git a/internal/handlers/descriptors/profiles.yaml b/internal/handlers/descriptors/profiles.yaml index 28957b33..1344ca0b 100644 --- a/internal/handlers/descriptors/profiles.yaml +++ b/internal/handlers/descriptors/profiles.yaml @@ -37,8 +37,8 @@ copy: profile from one server to another. This command has three required arguments. The first argument is the name of the profile to copy and it must exist on the source server. The `--from` argument accepts the - name of a named profile from the configuration file and designates the - source server. The `--to` argument accepts the anem of a named profile + name of a ipctl profile from the configuration file and designates the + source server. The `--to` argument accepts the name of a ipctl profile from the configuration file and designates the destination server. This command will first check if a profile by the same name exists on the diff --git a/internal/handlers/descriptors/projects.yaml b/internal/handlers/descriptors/projects.yaml index 711ae245..61140dbf 100644 --- a/internal/handlers/descriptors/projects.yaml +++ b/internal/handlers/descriptors/projects.yaml @@ -7,9 +7,9 @@ get: group: automation-studio description: | - Display one or more projects + Display one or more projects. - The `get projects` command will retieve all configured projects from + The `get projects` command will retrieve all configured projects from the server and output them in table format by default. If there are no configured projects, the command will return an empty table. @@ -22,7 +22,7 @@ describe: group: automation-studio description: | - Display details about a project + Display details about a project. The `describe project ` command will retrieve the specified project from the server, if it exists, and display it. If the @@ -37,7 +37,7 @@ create: group: automation-studio description: | - Create a new project + Create a new project. The `create project` command will create a new empty project with the specified name on the server. If a project with the same name already @@ -52,11 +52,11 @@ delete: group: automation-studio description: | - Delete a project + Delete a project. Use the `delete project` command to delete an existing project from the server. If the specified project does not exist on the server, - this command will return an error + this command will return an error. example: | # Delete a project named `cli test` @@ -67,19 +67,19 @@ copy: group: automation-studio description: | - Copy a project from one server to another + Copy a project from one server to another. The copy command can be used to copy a project from one Itential Automation - Platfom server to another one. + Platform server to another one. - The `name` argument sepcifies the Automation Studio Project name to copy - from one server to another. If it does not exist on the source server, - the command will return an error. + The `name` argument specifies the Automation Studio Project name to copy + from the source server to the target. If it does not exist on the source + server, the command will return an error. The command has two required options, `--from` and `--to`. The `--from` - option specifies the name of the profile that points to the server to - copy the project from. The `--to` option specifies the name of the profile - that points to the server to copy the project to. + option specifies the name of the ipctl profile that points to the server to + copy the project from. The `--to` option specifies the name of the ipctl + profile that points to the server to copy the project to. Both the `to` and `from` profiles must exist in the configuration file otherwise this command will produce an error. @@ -116,7 +116,7 @@ clear: group: automation-studio description: | - Delete all configured projects + Delete all configured projects. The `clear projects` command will delete all configured projects from the server. This is a destructive command and cannot be undone. @@ -130,14 +130,14 @@ import: group: automation-studio description: | - Import a project + Import a project. - The import command will import a project into IAP. The project name must - not already exist otherwise this command will return an error. + The import command will import a project into Itential Platform. If the + project name already exists this command will return an error. - When importing a project into IAP, the owner of the project will be based - on the credentials used to authenticate the `ipctl` client. Additional - members can be added to the project on import. + When importing a project into Itential Platform, the owner of the project + will be based on the credentials used to authenticate the `ipctl` client. + Additional members can be added to the project on import. To add a user or group account to the project on import, use the `--member` option. The `--member` option accepts a set of key=value @@ -159,4 +159,4 @@ export: exact_args: 1 description: | - Export a project + Export a project. diff --git a/internal/handlers/descriptors/roles.yaml b/internal/handlers/descriptors/roles.yaml index 0207907b..058b833a 100644 --- a/internal/handlers/descriptors/roles.yaml +++ b/internal/handlers/descriptors/roles.yaml @@ -7,20 +7,20 @@ get: group: admin-essentials description: | - Display one or more roles + Display one or more roles. The `get roles` command will retrieve all of the configured roles from the server and display them in table format. By default, the command will only display `Custom` roles and filter out all of the builtin roles. - To see all roles including the built in ones, use the `--all` command line + To see all roles including the builtin roles, use the `--all` command line option. example: | # Display all "Custom" roles that have been configured $ ipctl get roles - # Display all roles including builtin ones + # Display all roles including builtin roles $ ipctl get roles --all create: @@ -28,10 +28,10 @@ create: group: admin-essentials description: | - Create a new role + Create a new role. the `create role` command will add a new role to the server. The - commmand accepts a single argument `name` which uniquely identifies + command accepts a single argument `name` which uniquely identifies the role. If the role name already exists, this command will return an error. @@ -55,7 +55,7 @@ delete: group: admin-essentials description: | - Delete a role + Delete a role. The `delete role ` command is used to delete a custom role that has been configured on the server. This command can only delete roles that @@ -70,7 +70,7 @@ describe: group: admin-essentials description: | - Display detailed information about a role + Display detailed information about a role. When using the describe command, the name argument can take one of type forms depending on what you are trying to accomplish. The first form @@ -78,7 +78,7 @@ describe: information about. The second form is :. For instance, assume you want to see detailed information about the - adapters admin role. In this case, you woud use Adapters:admin as the + adapters admin role. In this case, you would use Adapters:admin as the input value to the describe command. example: | @@ -93,10 +93,10 @@ clear: group: admin-essentials description: | - Delete all configured roles + Delete all configured roles. The `clear roles` command will delete all custom configured roles from - the server. This is a destructive command that cannot be undone + the server. This is a destructive command that cannot be undone. example: | # Delete all custom roles @@ -107,14 +107,14 @@ copy: group: admin-essentials description: | - Copy a role from one server to another server + Copy a role from one server to another server. import: use: role group: admin-essentials description: | - Import a role to the target server + Import a role to the target server. The `import role` command will attempt to import a role define in a JSON document. The command accepts a single positional argument `path` @@ -132,4 +132,4 @@ export: group: admin-essentials description: | - Export a role from the target server + Export a role from the target server. diff --git a/internal/handlers/descriptors/roletypes.yaml b/internal/handlers/descriptors/roletypes.yaml index 97215773..6593daf8 100644 --- a/internal/handlers/descriptors/roletypes.yaml +++ b/internal/handlers/descriptors/roletypes.yaml @@ -10,7 +10,7 @@ get: Display one or more role types example: | - # Get the list of avalable role types + # Get the list of available role types $ ipctl get role-types diff --git a/internal/handlers/descriptors/templates.yaml b/internal/handlers/descriptors/templates.yaml index e2c9c428..934330b2 100644 --- a/internal/handlers/descriptors/templates.yaml +++ b/internal/handlers/descriptors/templates.yaml @@ -10,7 +10,7 @@ get: Display one or more templates The `get templates` command will return the list of configured templates - availalbe on the server. + available on the server. example: | # Get list of all templates @@ -34,7 +34,7 @@ create: will return an error. When creating a new template, the `--group` and `--type` options - are required. The `--group` option specifies the temaplate group + are required. The `--group` option specifies the template group to associate the new template with. The `--type` argument defines the type of template. Valid values are `textfsm` or `jinja2`. @@ -42,6 +42,9 @@ create: # Create a new TextFSM template $ ipctl create template ios-show --type textfsm --group cisco-ios + # Create a new Jinja2 template + $ ipctl create template my-config-template --type jinja2 --group config-templates + delete: use: template group: automation-studio diff --git a/internal/handlers/descriptors/workflows.yaml b/internal/handlers/descriptors/workflows.yaml index 9b499904..4117c6a1 100644 --- a/internal/handlers/descriptors/workflows.yaml +++ b/internal/handlers/descriptors/workflows.yaml @@ -6,26 +6,26 @@ get: use: workflows group: automation-studio description: | - Display one or more workflows + Display one or more workflows. describe: use: workflow group: automation-studio description: | - Display details about a workflow + Display details about a workflow. create: use: workflow group: automation-studio description: | - Create a new workflow + Create a new workflow. delete: use: workflow group: automation-studio description: | - Delete a workflow + Delete a workflow. The `delete workflow` command will delete an existing workflow from the Itential Platform server. If the specified workflow does not exist, @@ -36,26 +36,28 @@ copy: group: automation-studio description: | - Copy a workflow from one server to another + Copy a workflow from one server to another. - The `copy workflow` command will direclty copy a workflow asset from one + The `copy workflow` command will directly copy a workflow asset from one server to another. This command requires three values to work, the `name` - argument, the `--from` argument and the `--to` argument. + argument, the `--from` argument, and the `--to` argument. The required `name` argument specifies the name of the workflow to copy. The - `--from` argument accepts the name of a configured profile and defines the + `--from` argument accepts the name of a configured ipctl profile and defines the server to copy the workflow from. The `--to` argument accepts the name of a - configured profile and defines the server to copy the workflow to. + configured ipctl profile and defines the server to copy the workflow to. If the workflow specified by `name` does not exist on the source server, this command will return an error. Conversely, if the workflow specified by name - exists on the target server, this command will return an error. + exists on the target server, this command will return an error. In other words, + you can not copy a workflow that does not exist on the source server nor can + you overwrite an existing workflow on the target server. If either the `--from` or `--to` profile names do not exist in your - configureation file, this command will return an error. + configuration file, this command will return an error. - When copying a workflow asset from the source to target, any dependent assets - required by the workflow are not copied over. + When copying a workflow asset from the source to the target, any dependent + assets required by the workflow are not copied over. example: | @@ -67,18 +69,18 @@ clear: use: workflows group: automation-studio description: | - Delete all configured workflows + Delete all configured workflows. import: use: workflow group: automation-studio description: | - Import a workflow + Import a workflow. The `import workflow` command will attempt to import a workflow from the specified path. The required path argument should point to the JSON file - containing the worklow + containing the workflow. The workflow can be directly imported from a Git repository. To import the workflow from a Git repository, use the `--repository` command line option. @@ -94,22 +96,22 @@ import: $ ipctl import workflow path/to/test.workflow.json # Import a workflow from a repository - $ ipctl import workflow test.workflow.json --repository git@github.com:itential/worfklows.git + $ ipctl import workflow test.workflow.json --repository git@github.com:itential/workflows.git export: use: workflow group: automation-studio description: | - Export a workflow + Export a workflow. load: use: workflows group: automation-studio description: | - Load workflows + Load workflows. dump: use: workflows group: automation-studio description: | - Dump all workflows + Dump all workflows.