docs: itd command (#266)

Co-authored-by: Paola Nicosia <[email protected]>

Author: LiliumCandidum

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- new command: `itd`
+
 ## [v0.20.0] - 2025-07-28
 
 ### Changed

docs/10_overview.md

@@ -13,7 +13,9 @@ The `miactl` CLI functionalities can be summarized within its main subcommands:
 - `project`: view and manage the Projects of a specific Company
 - `serviceaccount`: create new service accounts for your Company
 - `runtime`: view and manage resources that are deployed on the runtime associated with the Project
-- `marketplace`: view and manage the Marketplace resources that are available for your Company
+- `marketplace`: view and manage the Marketplace resources that are available for your Company (deprecated from Mia-Platform Console v14.0.0).
+- `catalog`: view and manage the Marketplace resources that are available for your Company. It replaces the `marketplace` command. Available from Mia-Platform Console v14.0.0.
+- `itd`: view and manage Item Type Definitions. Available from Mia-Platform Console v14.1.0.
 
 ## Guides
 

docs/30_commands.md

@@ -532,11 +532,11 @@ miactl project describe [flags]
 
 Flags available for this command:
 
-- `--project-id`: required. The ID of the Application Project to describe 
-- `--revision`: for projects using Enhanced Workflow. The revision of the Application Project to describe 
-- `--version`: for projects using Enhanced Workflow. The version of the Application Project to describe 
-- `--branch`: for projects using the standard workflow. The branch of the Application Project to describe 
-- `--tag`: for projects using the standard workflow. The tag of the Application Project to describe 
+- `--project-id`: required. The ID of the Application Project to describe
+- `--revision`: for projects using Enhanced Workflow. The revision of the Application Project to describe
+- `--version`: for projects using Enhanced Workflow. The version of the Application Project to describe
+- `--branch`: for projects using the standard workflow. The branch of the Application Project to describe
+- `--tag`: for projects using the standard workflow. The tag of the Application Project to describe
 - `--output` or `-o`: output format. Allowed values: json, yaml (default is "json")
 
 ### apply
@@ -1215,7 +1215,7 @@ List Catalog items
 
 #### Synopsis
 
-List the Catalog items that the current user can access.
+List the Catalog items that the current user can access. Results are paginated and by default only the first page is shown.
 
 #### Usage
 
@@ -1225,7 +1225,8 @@ miactl catalog list --company-id company-id [FLAGS]...
 
 #### Flags
 
-- `--public` - if this flag is set, the command fetches not only the items from the requested company, but also the public Catalog items from other companies.
+- `--public` - if this flag is set, the command fetches not only the items from the requested company, but also the public item type definitions from other companies.
+- `--page` - specify the page to fetch, default is 1
 
 ### get
 
@@ -1320,3 +1321,96 @@ The flag `--item-id` or `-i` accepts the `itemId` of the Item.
 ```bash
 miactl catalog list-versions -i some-item
 ```
+
+## item type definition
+
+:::info
+This command and its subcommands use APIs that are only available from Mia-Platform Console v14.1.0.
+:::
+
+View and manage Item Type Definitions
+
+All the subcommands inherit the following flags:
+
+```sh
+      --auth-name string               the name of the miactl auth to use
+      --certificate-authority string   path to a cert file for the certificate authority for the selected endpoint
+      --company-id string              the ID of the Company
+  -c, --config string                  path to the config file default to $HOME/miactl/config
+      --context string                 the name of the miactl context to use
+      --endpoint string                the address and port of the Mia-Platform Console server
+      --insecure-skip-tls-verify       if true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
+  -v  --verbose                        increase the verbosity of the cli output
+```
+
+### list
+
+List Item Type Definitions
+
+#### Synopsis
+
+List the Item Type Definitions that the current user can access. Results are paginated and by default only the first page is shown.
+
+#### Usage
+
+```sh
+miactl itd list --company-id company-id [FLAGS]...
+```
+
+#### Flags
+
+- `--public` - if this flag is set, the command fetches not only the items from the requested company, but also the public Catalog items from other companies.
+- `--page` - specify the page to fetch, default is 1
+
+### get
+
+Get a Catalog item
+
+#### Synopsis
+
+Get an Item Type Definition
+
+You need to specify the name and its tenant namespace, via the respective flags. The company-id flag can be omitted if it is already set in the context.
+
+```bash
+miactl itd get --tenantId tenantId --name name
+```
+
+### delete
+
+Delete an Item Type Definition
+
+#### Synopsis
+
+Delete an Item Type Definition
+
+You need to specify the companyId and the item type definition name via the respective flags (recommended). The company-id flag can be omitted if it is already set in the context.
+
+```bash
+miactl itd delete --name name --version version ...
+```
+
+### put
+
+Create or update an Item Type Definition
+
+#### Synopsis
+
+Create or update an Item Type Definition.
+
+You need to specify the flag --file or -f that accepts a file, and companyId. Supported formats are JSON (.json files) and YAML (.yaml or .yml files).
+
+```bash
+miactl itd put -f file-path
+```
+
+#### Examples
+
+```bash
+
+# Create the item type definition in file myFantasticPluginDefinition.json located in the current directory
+miactl itd put --file myFantasticPluginDefinition.json
+
+# Create the item type definition in file myFantasticPluginDefinition.json, with relative path
+miactl itd put --file ./path/to/myFantasticPluginDefinition.json
+```

internal/cmd/catalog/list.go

@@ -34,7 +34,7 @@ const (
 
     you can also specify the following flags:
     - --public - if this flag is set, the command fetches not only the items from the requested company, but also the public Catalog items from other companies.
-		- -- page - specify the page to fetch, default is 1
+		- --page - specify the page to fetch, default is 1
     `
 	listCmdUse = "list --company-id company-id"
 )

internal/cmd/item-type-definition/delete.go

@@ -40,7 +40,7 @@ const (
 
 	You need to specify the companyId and the item type definition name via the respective flags (recommended). The company-id flag can be omitted if it is already set in the context.
 	`
-	deleteCmdUse = "delete { --name name --version version }"
+	deleteCmdUse = "delete --name name --version version"
 )
 
 func DeleteCmd(options *clioptions.CLIOptions) *cobra.Command {

internal/cmd/item-type-definition/put.go

@@ -51,11 +51,11 @@ const (
   Supported formats are JSON (.json files) and YAML (.yaml or .yml files). The company-id flag can be omitted if it is already set in the context.`
 
 	putExample = `
-  # Create the item type definition in file myFantasticGoTemplate.json located in the current directory
-  miactl catalog put --file myFantasticGoTemplate.json
+  # Create the item type definition in file myFantasticPluginDefinition.json located in the current directory
+  miactl catalog put --file myFantasticPluginDefinition.json
 
-  # Create the item type definition in file myFantasticGoTemplate.json, with relative path
-  miactl catalog put --file ./path/to/myFantasticGoTemplate.json`
+  # Create the item type definition in file myFantasticPluginDefinition.json, with relative path
+  miactl catalog put --file ./path/to/myFantasticPluginDefinition.json`
 
 	putCmdUse = "put { --file file-path }"
 )