ZDK CLI Commands

The following table summarizes the ZDK CLI commands that can be executed from your terminal.

Default options available across commands (except zdk help):

ZDK commands flow

This flowchart illustrates all the possible sequence of commands within ZDK CLI.

We will discuss the commands in detail:

1. zdk init

The zdk init command is used to initialize the ZDK CLI project directory. This command should be executed to create the necessary files and directories required for ZDK CLI configuration.

For example, the command  zdk init -n ZDKProject creates a new directory ZDKProject. All the subsequent commands have to be executed from the root of this directory.

• Error: Directory already exists
  Reason: The directory name that the user provided already exists in the same directory
  Resolution: Provide a different directory name
• Error: Error during file Creation
  Reason: This error during the initialization of a ZDK project signifies an issue with file creation or setup.
  Resolution: Check permissions and ensure you have the necessary access rights for file creation, or try from a different folder

2. zdk auth:login

zdk auth:login command is used to authenticate the user with Zoho CRM using a client account.

The zdk auth:login command redirects you to Zoho Accounts login page. 

After successful login, you will be prompted to select the CRM organization should connect with ZDK CLI. Select the required CRM organization and click on submit.

You will be redirected to a page where ZDK CLI requests permission to access the data in your Zoho account. Click Accept to provide these permissions to ZDK CLI. The outcome, whether successful or failure, will be communicated in the browser window as well as the terminal.

• Error during login. Environments specified in the API URL and bound with token do not match.
  Reason: This error is thrown when the domain url given in zdk-project.json does not match with the org that user has selected during login process.
  Resolution: Make sure you are choosing the sandbox org during authorization.
• Error during initialization of zdk. api supported only in sandbox environment.
  Reason: This error is thrown when the user does not select sandbox environment in the browser.
  Resolution: Make sure you are choosing the sandbox org during authorization.
• Error during login <server side error >.
  Resolution: Unexpected and unhandled exception in the server. Please contact our support team.

3. zdk auth:whoami

This command displays the currently logged in Zoho CRM org and the logged in user.

• There is no logged-in account for this project
  Reason: User has not logged into the zdk project
  Resolution: Execute whoami command only after logging in into a zdk project

4. zdk org:status

This command displays the changes made locally after the previous pull or push.

• Error: Directory not found. Aborting whole process
  Reason: When CRM directory is not present in the ZDK CLI Project directory.

  Resolution: Check whether CRM directory is present and if needed execute zdk pull command again.

• There is no logged-in account for this project.
  Reason: This error occurs when the command is executed from a ZDK project directory that is not logged in

  Resolution: Execute zdk org:status command after logging in into a zdk project

5. zdk org:pull

This command pulls the required metadata to the local ZDK CLI project directory. The meta.json file is used for specifying the metadata that needs to be pulled. You have the flexibility to choose between pulling all available supported metadata or specific types of metadata based on your requirements. The file ensures efficient and targeted retrieval of metadata.

Conflict may arise during the pull or push process when differences exist in the same file in the local and remote copies, leading to conflicting versions. The ZDK CLI cannot reconcile this without manual intervention. The zdk org:pull:resolve command is used to manually resolve the conflict.

There are two possible outcomes of zdk org:pull command

• User updates pulled content locally through zdk org:pull:update command. If conflict is not present, the content can be updated immediately. If a conflict is present the content can be updated after the conflict is resolved.
• User reverts the pulled content through the zdk org:pull:revert command.

The following commands should be carried out in sequence after zdk org:pull command.

If there are no conflicts, the sequence would be

1. zdk org:pull
2. zdk pull:update

If there are resolved conflicts, the sequence would be

1. zdk org:pull
2. zdk org:pull:resolve -f {{file_path}}
3. zdk org:pull:update

If the user reverts the pull operation, the sequence would be

1. zdk org:pull
2. zdk org:pull:revert

• Error:Meta.json file not found. zdk initis not successful.
  Reason: This error is thrown when meta.json is not found.
  Resolution: Execute zdk init again or create meta.json file under the ZDK CLI Project directory with proper JSON structure.
• Error during pull : Allowed 'resource_type' values are 'all|specific'.
  Reason: When resource_type value other than all|specific is provided.
  Resolution: Give valid value for resource_type. Note that it is case sensitive.
• Error during pull : Key 'resources' is missing.
  Reason: When resource_type is specific and resources is not provided.
  Resolution: Give valid value for resources.
• Error during pull : Key 'resources' should not be empty.
  Reason: When resource_type is specific and resources is an empty array.
  Resolution: Give valid value for resources.
• Error during pull : Key 'resources[0].resource_type' is missing.
  Reason: When resource_type is specific and resources JSON object is empty and resource_type not given.
  Resolution: Give valid value for resources and resource_type.
• Error during pull : Check for the allowed values in 'resources[0].resource_type' . The allowed resource_types are modules,fields,layouts,widgets,profiles,roles.
  Reason: When resource_type is specific and When resource_type is specific and resources.resource_type is not the specified value.
  Resolution: Give valid value for resources.resource_type: modules,fields,layouts,widgets,profiles,roles.
• Error during pull: Check for the allowed values in 'resources[0].resource_type' . The allowed resource_types are modules,fields,layouts,widgets,profiles,roles.
  Reason: When resource_type is specific and resources.resource_type is not the specified value.
  Resolution: Give valid value for resources.resource_type: modules,fields,layouts,widgets,profiles,roles.
• Error during pull : Key 'resources[0].resource_type' is missing.
  Reason: When resource_type is specific and resources.resources is not provided.
  Resolution: Give valid value for resources.resources.
• Error during pull : Expected Data type is JSONArray for key 'resources[0].resources'.
  Reason: When resource_type is specific and resources.resources is not JSONArray data type.
  Resolution: Give valid data type for resources.resources.
• Error during pull : Key 'resources[0].resources' should not be empty.
  Reason: When resource_type is specific and resources.resources is of empty JSON array.
  Resolution: Give non empty, valid value for resources.resources.
• Error during pull : Key 'resources[0].resources[0].api_name' is missing.
  Reason: When resource_type is specific and resources.resources.apiname is not given.
  Resolution: Give non empty, valid value for resources.resources.apiname
• Error during pull : invalid data { "api_name": "api_name", "json_path": "$.resources[0].resources[0].api_name" }
  Reason: When resource_type is specific and resources.resources.apiname is not a valid value .
  Resolution: Give valid value for resources.resources.apiname
• Error: Meta.json file not found. zdk init is not successful
  Reason: The meta.json file is not present during the pull operation.
  Resolution: Provide a valid meta.json file.
• Error: File extraction failed. Accessing of zip file failed. Access error : <filename>
  Reason: This error occurs when zip file downloaded from server is corrupt.
  Resolution: Please contact our support team.

6. zdk org:pull:resolve -f {file_path}

This command is used to resolve differences between the remote file and the local file, and once resolved, mark it as resolved. It shows the difference between files during merge conflict.

It opens a window in the browser showing the difference. By default, it opens a three-way difference editor. However, it is possible to switch to a two-way diff editor as well.

In the three-way diff editor, three files are displayed: the local file (containing local content), the base file (editable and intended to replace the local file upon submission), and the remote file (containing content from the remote source).

In the two-way editor, two files are displayed: the local file (editable and intended to replace the local file upon submission) and the remote file (content from the remote source).

This command opens up the browser with the diff editor.

The browser editor will display the changed file in the terminal, the file before the changes, and the remote file. You can modify the base file with the required changes and hit on submit. This will mark the file as resolved.

Editor options for zdk org:pull:resolve command

Various diff editor options are available in ZDK CLI, which can be chosen using the --tool parameter.

Here {toolname} could be any of the supported tools, which are

1. Meld
2. Kdiff3
3. vim
4. vimdiff

Closing the file showing difference in vimdiff tool with :wq will resolve it.

If the tool mentioned in the command is not installed in your system, then error will be thrown as " Tool cannot be found in your system. Error during resolve operation"

• Error: Error during resolve operation.
  Reason: Resolve error failed due to an app error
  Resolution: Check the JSON structure of the meta file for correctness.
• Error: No file path provided.
  Reason: File path is not provided.
  Resolution: Provide the correct path of file to be resolved.
• Error:Conflict file not present.
  Reason: When user entered the wrong conflict file for resolve.
  Resolution: Provide the correct conflict file.
• Error: Tool cannot be found in your system.
  Reason: Resolve tool cannot be found.
  Resolution: Use existing tool or install required tool.

7. zdk org:pull:revert

This command reverts the previous zdk org:pull command that was executed. This can be executed when the pull process is initiated, and before executing the zdk org:pull:update command . We cannot use it once the update process is completed

For example, this command can be used when you execute a zdk org:pull command and there are multiple conflicts and you decide to resolve the conflicts at a later stage. By executing the zdk org:pull:revert command, you can work with the previous folder structure.

Note that when zdk org:pull:revert command is executed, any changes made in the local folder structure after the previous zdk org:pull command execution, will also be reverted.

• Error: Revert process failed.
  Reason: This error occurs when revert process fails because the backup contents necessary for the zdk org:pull:revert command is not available locally.
  Resolution: Proceeding with the zdk org:pull:revert command is not possible in this scenario. To proceed, resolve the conflict and update the local directory.

8. zdk org:pull:update

This command updates the local directory with the pulled data. It can be executed only when all conflicts are resolved.

• Error: Conflicts are not resolved.
  Reason: This error occurs when user tries to update without resolving conflicts
  Resolution: Resolve the conflict using zdk org:pull:resolve command.

9. zdk org:push

This command updates the local changes to the server. This is an asynchronous command where the status of the push can be seen using the zdk org:push:result command.

The result can be viewed through the zdk org:push:result --jobid {id} command. If conflicts are found, it has to be resolved through zdk org:pull:resolve command. Please note that the zdk org:push command requires the absence of conflicts to function properly. When the zdk org:push command is executed, if the local changes conflicts with the remote changes it will be notified in the response. Then user should run the zdk org:pull command and resolve the conflicts in local before the zdk org:push command is executed again.

Behaviour of files listed in .zdkignore file when zdk org:push command is executed
When a user adds a new metadata file and lists its entry in the .zdkignore file, executing the zdk org:push command will push all files except those listed in .zdkignore. The newly created file will remain locally after a successful push.
If a user updates an existing metadata file locally and then adds its entry to the .zdkignore file, the zdk org:push command will push other files while ignoring those listed in .zdkignore. After the push, the file in the .zdkignore file will not be updated on the remote, but the changes will remain locally.

• Error: Merge Conflicts! Try zdk org:pull. Use --help for more information.
  Reason: This error occurs merge conflict exists.
  Resolution: Resolve the conflict using zdk org:pull:resolve
• Error: zip not created properly.
  Reason: This error occurs when the user does not have permission to create the zip file in the directory.
  Resolution: Check the permissions of the directory. If the issue persists, please contact our support team.
• Error: Improper file name <file name>.
  Reason: When file path regex not correct.
  Resolution: Correct the file name and try again.
• Error: Required data for the meta missing <file name>.
  Reason: This error occurs when <file name> is not found in the widgets project directory under crm/widgets/{WidgetAPIName}.
  Resolution: Try creating the file in widget projects under crm/widgets directory using zet command with proper widgets API name.
• Error: Required File Missing / check whether user has permission for this resource.
  Reason: This case happens for widgets/ when user has no permission for widgets or when widgets data file is missing.
  Resolution: Make sure that you have permission in the org for widgets. Also, check whether the data directory is created for internal widgets. If issue persists, please contact our support team.

10. zdk org:push:result --jobid {id}

This command displays the result of the push process with the mentioned job id and updates the local directory. For new metadata json files, the complete configurations will get updated in the JSON file after the zdk org:push:result command is executed.

Response categories

Success Responses: Files listed in this section have been successfully processed and will be reflected on the server.

Roll backed Responses: Files listed in this section are valid files that have encountered rollbacks due to failures in other files within the same transaction.

Error Responses: Files listed in this section contain errors that require resolution and re-submission to ensure they are correctly reflected on the server.

ZDK CLI transaction types

UI Component Oriented Metadata Transaction: In this method, profiles, roles, modules, fields, and layouts are processed in a single transaction. If any issue occurs during the push of any of these resources, it will result in a rollback of the entire transaction.

Developer Centric Metadata Transaction:: In this method each widget is processed as a separate transaction. If two widgets are being processed and one encounters an issue, it will not affect the creation of the other widget.

Constraints

• At a time only one zdk org:push command can be processed.
• Subform, multi-select lookup, multi-user lookup, multi-module lookup, rollup summary, formula fields are not supported in the Beta release.
• It is recommended to use one dedicated org for a single zdk project.
• The meta:create field command in the ZDK CLI covers only the basic type for fields resource.
• In case the sandbox gets corrupted, you will have to rebuild the sandbox.

• Error: JobId is required.
  Reason: This error occurs when job id is not provided in zdk org:push:result --jobid command.
  Resolution: Provide job id in the command.
• Error: Result already executed. Try zdk org:push:list. Use --help for more information.
  Reason: This error occurs when job id is already executed using this command.
  Resolution: You can use -f option to execute the command, but it may result in lose of local changes, if any.

11. zdk org:push:list

This command lists the last 10 push job ids, the push status and the details of the push status in a tabular format.

• Error: Error while fetching the push list details.
  Reason: This error occurs when the server connection is facing issues.
  Resolution: Please contact our support team.

12. zdk org:list

This command lists the orgs linked with the current user in a tabular format.

• Error: Error while fetching of orgs.
  Reason: This error occurs when the server connection is facing issues.
  Resolution: Please contact our support team.

13. zdk org:export

This command exports the crm directory and creates a zip in the project directory. Developers can use the zip to share the metadata with the other developers who want to deploy the same metadata in their corresponding CRM org.

• Error: Error during export.
  Reason: This error occurs when zipping of files didnt get completed.
  Resolution: Check the permissions of the directory. If issue persists, please contact our support team.

14. zdk meta:create

This commands creates a new metadata. Supported metadata are modules, fields, layouts, widgets, profiles, and roles.

Valid metadata types are modules, fields, layouts, widgets, profiles, and roles.

Based on the specified metadata type in the command, the runtime input will be requested, and a meta file will be created in the corresponding directory.

The runtime inputs given in this command are static inputs. Dynamic properties should be given manually inside the file after zdk meta:create {type} command. For eg: If you want to create a picklist field, you will not be asked to enter picklist values in the command line. Instead, you should add them manually inside the file after creation.

• Error: Error during creation of meta file.
  Reason: This error occurs when permissions might not be provided for the directory.
  Resolution: Check the permissions of the directory. If the issue persists, please contact our support team.
• Error: Missing required argument 'type'.
  Reason: This error occurs when the command is executed without mentioning type.
  Resolution: Give the command in correct format : zdk meta:create [options] {type}.

15. zdk help

This command lists all the commands with its description.

16. zdk auth:logout

This commands logs out ZDK CLI from your CRM account.

• Error: There is no logged-in account for this project.
  Reason: User has not logged into the ZDK CLI project.
• Error during revoking the token/ Token already revoked.
  Reason: When access is already revoked for the session.