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