InstructLab CLI

Globals

Options

--project-id (string): The InstructLab project ID.
--output (string): Choose an output format - can be 'json', 'yaml', or 'table'. Defaults to 'table'.
-j, --jmes-query (string): Provide a JMESPath query to customize output.
-q, --quiet: Suppresses verbose messages.
-v, --version: Prints the plug-in version.

Example

ibmcloud ilab
    --project-id=project_id \
    --output=json \
    --jmes-query="[:10]" \
    --quiet

Note: This example only demonstrates the global options available to all sub-commands and is not a valid command itself.

Config

Global parameters can also be stored in persistent configuration so that they do not need to be manually specified each time the plug-in is invoked. Each parameter can be configured with the config command and its subcommands.

ibmcloud ilab config

`ibmcloud ilab config set`

Set a new config value for a specific option. Each subcommand of the set command maps to a global option. Each subcommand accepts a single argument, the string representation of the value to store for the option.

ibmcloud ilab config set <option> <value>

Examples

`ibmcloud ilab config get`

Print out the currently set value for a specific option. Each subcommand of the get command maps to a global option.

ibmcloud ilab config get <option>

Examples

`ibmcloud ilab config unset`

Unset the currently set value for a specific option. Each subcommand of the unset command maps to a global option.

The subcommands available for this service are: .

ibmcloud ilab config unset <option>

Examples

`ibmcloud ilab config list`

List out all of the currently set config values.

ibmcloud ilab config list

Examples

ibmcloud ilab config list

Taxonomy

Operations to manage taxonomies.

ibmcloud ilab taxonomy --help

`ibmcloud ilab taxonomy add`

Add a taxonomy to your Cloud Object Storage bucket.

ibmcloud ilab taxonomy add --name NAME [--taxonomy-path TAXONOMY-PATH] [--taxonomy-path-cos TAXONOMY-PATH-COS] [--cos-bucket-information COS-BUCKET-INFORMATION | --cos-id COS-ID --cos-bucket COS-BUCKET --cos-endpoint COS-ENDPOINT] [--secrets-manager-config SECRETS-MANAGER-CONFIG | --secrets-manager-git-url SECRETS-MANAGER-GIT-URL --secrets-manager-git-id SECRETS-MANAGER-GIT-ID]

Command options

--name (string)

The name you want to give your taxonomy. Required.

The maximum length is 32 characters. The minimum length is 1 character. The value must match regular expression /^[a-zA-Z0-9]([_-]?[a-zA-Z0-9]+)*$/.

--taxonomy-path (string)

The absolute or relative path to the taxonomy.tar.gz file on your local machine. For example 'Downloads/taxonomy.tar.gz'.

The maximum length is 100 characters. The minimum length is 10 characters. The value must match regular expression /^(?:[a-zA-Z]:\\\\|\\.{0,2}[\\\/]|\/)?(?:[^\\\/:*?"<>|\\r\\n]+[\\\/])*[^\\\/:*?"<>|\\r\\n]*$/.

--taxonomy-path-cos (string)

The path in your Cloud Object Storage bucket where you want to store your taxonomy. By default, taxonomies are stored at 'taxonomies/taxonomy-<current_time>.tar.gz'.

The maximum length is 100 characters. The minimum length is 20 characters. The value must match regular expression /^([-_.\/a-zA-Z0-9][a-zA-Z0-9]+)*[^\/]$/.

--cos-bucket-information (CosBucketInformationPrototype)

Cloud Object Storage bucket information. This JSON option can instead be provided by setting individual fields with other options. It is mutually exclusive with those options.

Provide a JSON string option or specify a JSON file to read from by providing a filepath option that begins with a @, e.g. --cos-bucket-information=@path/to/file.json.

--secrets-manager-config (SecretsManagerConfigPrototype)

Secrets Manager configuration details. This JSON option can instead be provided by setting individual fields with other options. It is mutually exclusive with those options.

Provide a JSON string option or specify a JSON file to read from by providing a filepath option that begins with a @, e.g. --secrets-manager-config=@path/to/file.json.

--cos-id (string)

Your Cloud Object Storage instance ID. This option is only required when you want InstructLab to automatically create a bucket in your Object Storage instance. This option provides a value for a sub-field of the JSON option 'cos-bucket-information'. It is mutually exclusive with that option.

The maximum length is 100 characters. The minimum length is 20 characters. The value must match regular expression /^[a-z0-9-]+$/.

-b, --cos-bucket (string)

The Cloud Object Storage bucket where you want to storage your taxonomy.tar.gz. This option provides a value for a sub-field of the JSON option 'cos-bucket-information'. It is mutually exclusive with that option.

The maximum length is 63 characters. The minimum length is 3 characters. The value must match regular expression /^[a-zA-Z0-9]([.-]?[a-zA-Z0-9]+)*$/.

-e, --cos-endpoint (string)

The endpoint to the Cloud Object Storage bucket. This option provides a value for a sub-field of the JSON option 'cos-bucket-information'. It is mutually exclusive with that option.

The maximum length is 300 characters. The minimum length is 13 characters. The value must match regular expression /^https:\/\/([a-zA-Z0-9-]+\\.)*cloud-object-storage(?:\\.test)?\\.appdomain\\.cloud$/.

--secrets-manager-git-url (string)

The URL to a Secrets Manager instance to retrieve your user-defined secrets. The credentials in your Secrets Manager instance are used to retrieve the knowledge documents that are referenced in your taxonomy from the repository where they're stored. This option provides a value for a sub-field of the JSON option 'secrets-manager-config'. It is mutually exclusive with that option.

The maximum length is 300 characters. The minimum length is 13 characters. The value must match regular expression /^https:\/\/([a-zA-Z0-9-]+\\.)*secrets-manager(?:\\.test)?\\.appdomain\\.cloud$/.

--secrets-manager-git-id (string)

The Secrets Manager ID that points to your personal authorization token and URL in JSON format. The credentials in your Secrets Manager instance are used to retrieve the knowledge documents that are referenced in your taxonomy from the repository where they're stored. This option provides a value for a sub-field of the JSON option 'secrets-manager-config'. It is mutually exclusive with that option.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /^[a-z0-9-]+$/.

Examples

ibmcloud ilab taxonomy add \
    --name example-taxonomy-1 \
    --taxonomy-path exampleString \
    --taxonomy-path-cos taxonomies/taxonomy.tar.gz \
    --cos-bucket-information '{"service_instance_id": "628e4348-2183-42fa-a03a-6f0f78453530", "bucket": "example-bucket-1", "endpoint": "https://s3.us-east.cloud-object-storage.appdomain.cloud"}' \
    --secrets-manager-config '{"url": "https://12345678-abcd-1234-5678-abcdefghijkl.us-east.secrets-manager.appdomain.cloud", "git_id": "d9428888-122b-11e1-b85c-61cd3cbb3210"}'

Alternatively, granular options are available for the sub-fields of JSON string options:

ibmcloud ilab taxonomy add \
    --name example-taxonomy-1 \
    --taxonomy-path exampleString \
    --taxonomy-path-cos taxonomies/taxonomy.tar.gz \
    --cos-id 628e4348-2183-42fa-a03a-6f0f78453530 \
    --cos-bucket example-bucket-1 \
    --cos-endpoint https://s3.us-east.cloud-object-storage.appdomain.cloud \
    --secrets-manager-git-url https://12345678-abcd-1234-5678-abcdefghijkl.us-east.secrets-manager.appdomain.cloud \
    --secrets-manager-git-id d9428888-122b-11e1-b85c-61cd3cbb3210

`ibmcloud ilab taxonomy list`

Lists the details of a collection of taxonomy resources.

ibmcloud ilab taxonomy list

Example

ibmcloud ilab taxonomy list

Default JMESPath

A JMESPath query will be applied to this output of this command by default, if one is not provided by the user. The exact query will depend on the scenario and the output format requested. You can see the condition for each default JMESPath query in the following table:

Default JMESPath
Response	Output	Query
Success	Default
	Table	`taxonomies[].{id:id,name:name,taxonomy_path_cos:taxonomy_path_cos,created_at:created_at,state:state,status:status}`

If a custom JMESPath query is provided, it will replace any of the JMESPath in the table above.

`ibmcloud ilab taxonomy get`

Gets the details of a taxonomy resource.

ibmcloud ilab taxonomy get --id ID

Command options

--id (string)

Unique Identifier to a taxonomy. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /^[a-z0-9-]+$/.

Example

ibmcloud ilab taxonomy get \
    --id 817bc95a-fef0-4039-b936-e0b6fb17b723

Default JMESPath

Default JMESPath
Response	Output	Query
Success	Default
	Table	`{id:id,name:name,project_id:project_id,taxonomy_path_cos:taxonomy_path_cos,created_at:created_at,state:state,status:status}`

If a custom JMESPath query is provided, it will replace any of the JMESPath in the table above.

`ibmcloud ilab taxonomy delete`

Deletes a taxonomy resource.

ibmcloud ilab taxonomy delete --id ID

Command options

--id (string)

Unique Identifier to a taxonomy. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /^[a-z0-9-]+$/.

Example

ibmcloud ilab taxonomy delete \
    --id 817bc95a-fef0-4039-b936-e0b6fb17b723

Data

Operations to manage data.

ibmcloud ilab data --help

`ibmcloud ilab data generate`

Generates data against a specified taxonomy resource.

ibmcloud ilab data generate --name NAME [--taxonomy-id TAXONOMY-ID] [--data-destination DATA-DESTINATION | --output-cos-bucket OUTPUT-COS-BUCKET --output-cos-endpoint OUTPUT-COS-ENDPOINT] [--data-sources DATA-SOURCES | --internal-ids INTERNAL-IDS --skills-paths SKILLS-PATHS --knowledge-paths KNOWLEDGE-PATHS --skills-knowledge-cos-bucket SKILLS-KNOWLEDGE-COS-BUCKET --skills-knowledge-cos-endpoint SKILLS-KNOWLEDGE-COS-ENDPOINT --data-sources-user-provided-paths DATA-SOURCES-USER-PROVIDED-PATHS]

Command options

--name (string)

The name to give a data resource. Required.

The maximum length is 32 characters. The minimum length is 1 character. The value must match regular expression /^[a-zA-Z0-9]([_-]?[a-zA-Z0-9]+)*$/.

--taxonomy-id (string)

The taxonomy ID that was used for synthetic data generation. In model training, this value is used for validating the data ID. This value is available only after the model training job is accepted by an agent.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /^[a-z0-9-]+$/.

--data-destination (DataDestinationPrototype)

Output Cloud Object Storage bucket information. This JSON option can instead be provided by setting individual fields with other options. It is mutually exclusive with those options.

Provide a JSON string option or specify a JSON file to read from by providing a filepath option that begins with a @, e.g. --data-destination=@path/to/file.json.

--data-sources (DataSourcesPrototype)

Data sources associated with the taxonomy. This JSON option can instead be provided by setting individual fields with other options. It is mutually exclusive with those options.

Provide a JSON string option or specify a JSON file to read from by providing a filepath option that begins with a @, e.g. --data-sources=@path/to/file.json.

--output-cos-bucket (string)

The Cloud Object Storage that the output will be stored in. This option provides a value for a sub-field of the JSON option 'data-destination'. It is mutually exclusive with that option.

The maximum length is 63 characters. The minimum length is 3 characters. The value must match regular expression /^[a-zA-Z0-9]([.-]?[a-zA-Z0-9]+)*$/.

--output-cos-endpoint (string)

The endpoint to the output Cloud Object Storage bucket. This option provides a value for a sub-field of the JSON option 'data-destination'. It is mutually exclusive with that option.

--internal-ids ([]strfmt.UUID)

List of internal UUIDs referencing data sources. This option provides a value for a sub-field of the JSON option 'data-sources'. It is mutually exclusive with that option.

The list items must match regular expression /^[a-z0-9-]+$/. The maximum length is 20 items. The minimum length is 0 items.

--skills-paths ([]string)

A set of user provided skills json files present in an authorized Cloud Object Storage bucket containing curated data for fine-tuning. Each file must not exceed 100 GB in size. The accumulative size of all the skills and knowledge json files (including the files from internal ids, if provided) must not exceed 400 GB. This option provides a value for a sub-field of the JSON option 'data-sources'. It is mutually exclusive with that option.

The list items must match regular expression /^([-_.\/a-zA-Z0-9][a-zA-Z0-9]+)*[^\/]$/. The maximum length is 20 items. The minimum length is 0 items.

--knowledge-paths ([]string)

A set of user provided knowledge json files present in an authorized Cloud Object Storage bucket containing curated data for fine-tuning. Each file must not exceed 100 GB in size. The accumulative size of all the skills and knowledge json files (including the files from internal ids, if provided) must not exceed 400 GB. This option provides a value for a sub-field of the JSON option 'data-sources'. It is mutually exclusive with that option.

The list items must match regular expression /^([-_.\/a-zA-Z0-9][a-zA-Z0-9]+)*[^\/]$/. The maximum length is 20 items. The minimum length is 0 items.

--skills-knowledge-cos-bucket (string)

The Cloud Object Storage bucket where skills/knowledge jsonl is stored. This option provides a value for a sub-field of the JSON option 'data-sources'. It is mutually exclusive with that option.

The maximum length is 63 characters. The minimum length is 3 characters. The value must match regular expression /^[a-zA-Z0-9]([.-]?[a-zA-Z0-9]+)*$/.

--skills-knowledge-cos-endpoint (string)

The endpoint to the Cloud Object Storage bucket. This option provides a value for a sub-field of the JSON option 'data-sources'. It is mutually exclusive with that option.

--data-sources-user-provided-paths (UserProvidedPathsPrototype)

User-provided file paths for skills and knowledge training data. Each file must not exceed 100 GB in size. The accumulative size of all the skills and knowledge json files (including the files from internal ids, if provided) must not exceed 400 GB. This option provides a value for a sub-field of the JSON option 'data-sources'. It is mutually exclusive with that option.

Provide a JSON string option or specify a JSON file to read from by providing a filepath option that begins with a @, e.g. --data-sources-user-provided-paths=@path/to/file.json.

Examples

ibmcloud ilab data generate \
    --name example-data-1 \
    --taxonomy-id 202a03c4-dcf1-432a-82b7-abecb2e019f7 \
    --data-destination '{"bucket": "example-bucket-1", "endpoint": "https://s3.us-east.cloud-object-storage.appdomain.cloud"}' \
    --data-sources '{"internal_ids": ["9e0a5988-0c7d-44de-ba48-465aef67baee","9e0a5988-0c7d-44de-ba48-465aef67baee"], "skills": ["user_provided_path/skills/skills_1.jsonl","user_provided_path/skills/skills_1.jsonl"], "knowledge": ["user_provided_path/knowledge/knowledge1.jsonl","user_provided_path/knowledge/knowledge1.jsonl"], "bucket": "example-bucket-1", "endpoint": "https://s3.us-east.cloud-object-storage.appdomain.cloud", "user_provided_paths": {"skills": ["user_provided_path/skills/skills_1.jsonl","user_provided_path/skills/skills_1.jsonl"], "knowledge": ["user_provided_path/knowledge/knowledge1.jsonl","user_provided_path/knowledge/knowledge1.jsonl"], "cos_bucket_information": {"bucket": "example-bucket-1", "endpoint": "https://s3.us-east.cloud-object-storage.appdomain.cloud"}}}'

Alternatively, granular options are available for the sub-fields of JSON string options:

ibmcloud ilab data generate \
    --name example-data-1 \
    --taxonomy-id 202a03c4-dcf1-432a-82b7-abecb2e019f7 \
    --output-cos-bucket example-bucket-1 \
    --output-cos-endpoint https://s3.us-east.cloud-object-storage.appdomain.cloud \
    --internal-ids 9e0a5988-0c7d-44de-ba48-465aef67baee,9e0a5988-0c7d-44de-ba48-465aef67baee \
    --skills-paths user_provided_path/skills/skills_1.jsonl,user_provided_path/skills/skills_1.jsonl \
    --knowledge-paths user_provided_path/knowledge/knowledge1.jsonl,user_provided_path/knowledge/knowledge1.jsonl \
    --skills-knowledge-cos-bucket example-bucket-1 \
    --skills-knowledge-cos-endpoint https://s3.us-east.cloud-object-storage.appdomain.cloud \
    --data-sources-user-provided-paths userProvidedPathsPrototype

`ibmcloud ilab data list`

Lists the details of a collection of data resources.

ibmcloud ilab data list

Example

ibmcloud ilab data list

Default JMESPath

Default JMESPath
Response	Output	Query
Success	Default
	Table	`data[].{id:id,name:name,state:state,status:status,created_at:created_at,completed_at:completed_at}`

If a custom JMESPath query is provided, it will replace any of the JMESPath in the table above.

`ibmcloud ilab data get`

Gets the details of a data resource.

ibmcloud ilab data get --id ID

Command options

--id (string)

Unique Identifier to data run. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /^[a-z0-9-]+$/.

Example

ibmcloud ilab data get \
    --id 817bc95a-fef0-4039-b936-e0b6fb17b723

Default JMESPath

Default JMESPath
Response	Output	Query
Success	Default
	Table	`{id:id,name:name,project_id:project_id,state:state,status:status,created_at:created_at,completed_at:completed_at}`

If a custom JMESPath query is provided, it will replace any of the JMESPath in the table above.

`ibmcloud ilab data delete`

Deletes a data resource.

ibmcloud ilab data delete --id ID

Command options

--id (string)

Unique Identifier to data run. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /^[a-z0-9-]+$/.

Example

ibmcloud ilab data delete \
    --id 817bc95a-fef0-4039-b936-e0b6fb17b723

`ibmcloud ilab data cancel`

Cancels the generation of synthetic data.

ibmcloud ilab data cancel --id ID

Command options

--id (string)

Unique Identifier to data run. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /^[a-z0-9-]+$/.

Example

ibmcloud ilab data cancel \
    --id 817bc95a-fef0-4039-b936-e0b6fb17b723

Model

Operations to manage models.

ibmcloud ilab model --help

`ibmcloud ilab model train`

Trains a model against the specified synthetic data.

ibmcloud ilab model train --name NAME --data-id DATA-ID

Command options

--name (string)

The name to give a model resource. Required.

The maximum length is 32 characters. The minimum length is 1 character. The value must match regular expression /^[a-zA-Z0-9]([_-]?[a-zA-Z0-9]+)*$/.

--data-id (string)

The ID of the synthetic data generation (SDG) run. You can use this ID to monitor the data generation process. After SDG is complete, your can this ID to retrieve the synthetic data. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /^[a-z0-9-]+$/.

Example

ibmcloud ilab model train \
    --name example-model-1 \
    --data-id add785e6-a8c3-4f5f-ab89-c506a3f115da

`ibmcloud ilab model list`

Lists your model resources.

ibmcloud ilab model list

Example

ibmcloud ilab model list

Default JMESPath

Default JMESPath
Response	Output	Query
Success	Default
	Table	`models[].{created_at:created_at,completed_at:completed_at,id:id,name:name,state:state,status:status}`

If a custom JMESPath query is provided, it will replace any of the JMESPath in the table above.

`ibmcloud ilab model get`

Gets the details of a model.

ibmcloud ilab model get --id ID

Command options

--id (string)

Unique Identifier to a model training run. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /^[a-z0-9-]+$/.

Example

ibmcloud ilab model get \
    --id 817bc95a-fef0-4039-b936-e0b6fb17b723

Default JMESPath

Default JMESPath
Response	Output	Query
Success	Default
	Table	`{base_model:base_model,created_at:created_at,completed_at:completed_at,data_id:data_id,id:id,name:name,project_id:project_id,state:state,status:status}`

If a custom JMESPath query is provided, it will replace any of the JMESPath in the table above.

`ibmcloud ilab model delete`

Delete a model.

ibmcloud ilab model delete --id ID

Command options

--id (string)

Unique Identifier to a model training run. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /^[a-z0-9-]+$/.

Example

ibmcloud ilab model delete \
    --id 817bc95a-fef0-4039-b936-e0b6fb17b723

`ibmcloud ilab model cancel`

Cancels the training of a model.

ibmcloud ilab model cancel --id ID

Command options

--id (string)

Unique Identifier to a model training run. Required.

The maximum length is 36 characters. The minimum length is 36 characters. The value must match regular expression /^[a-z0-9-]+$/.

Example

ibmcloud ilab model cancel \
    --id 817bc95a-fef0-4039-b936-e0b6fb17b723

Schema examples

The following schema examples represent the data that you need to specify for a command option. These examples model the data structure and include placeholder values for the expected value type. When you run a command, replace these values with the values that apply to your environment as appropriate.

CosBucketInformationPrototype

The following example shows the format of the CosBucketInformationPrototype object.


{
  "service_instance_id" : "628e4348-2183-42fa-a03a-6f0f78453530",
  "bucket" : "example-bucket-1",
  "endpoint" : "https://s3.us-east.cloud-object-storage.appdomain.cloud"
}

DataDestinationPrototype

The following example shows the format of the DataDestinationPrototype object.


{
  "bucket" : "example-bucket-1",
  "endpoint" : "https://s3.us-east.cloud-object-storage.appdomain.cloud"
}

DataSourcesPrototype

The following example shows the format of the DataSourcesPrototype object.


{
  "internal_ids" : [ "9e0a5988-0c7d-44de-ba48-465aef67baee", "9e0a5988-0c7d-44de-ba48-465aef67baee" ],
  "skills" : [ "user_provided_path/skills/skills_1.jsonl", "user_provided_path/skills/skills_1.jsonl" ],
  "knowledge" : [ "user_provided_path/knowledge/knowledge1.jsonl", "user_provided_path/knowledge/knowledge1.jsonl" ],
  "bucket" : "example-bucket-1",
  "endpoint" : "https://s3.us-east.cloud-object-storage.appdomain.cloud",
  "user_provided_paths" : {
    "skills" : [ "user_provided_path/skills/skills_1.jsonl", "user_provided_path/skills/skills_1.jsonl" ],
    "knowledge" : [ "user_provided_path/knowledge/knowledge1.jsonl", "user_provided_path/knowledge/knowledge1.jsonl" ],
    "cos_bucket_information" : {
      "bucket" : "example-bucket-1",
      "endpoint" : "https://s3.us-east.cloud-object-storage.appdomain.cloud"
    }
  }
}

SecretsManagerConfigPrototype

The following example shows the format of the SecretsManagerConfigPrototype object.


{
  "url" : "https://12345678-abcd-1234-5678-abcdefghijkl.us-east.secrets-manager.appdomain.cloud",
  "git_id" : "d9428888-122b-11e1-b85c-61cd3cbb3210"
}

UserProvidedPathsPrototype

The following example shows the format of the UserProvidedPathsPrototype object.


{
  "bucket" : "example-bucket-1",
  "endpoint" : "https://s3.us-east.cloud-object-storage.appdomain.cloud"
}