Sign Up
  1. Znode
  2. Solution home
  3. Developer Documentation - V10
  4. Developer Quickstart Guides - V10

How to Install and Set Up Znode CLI

TABLE OF CONTENTS

This article is a complete step-by-step guide for setting up the Znode custom development environment on a local machine. It also provides instructions for deploying custom changes into the Block Box environment. This document is intended for Znode custom implementation developers (internal or external).

Overview

The Znode CLI is a command-line utility that provides commands to download various Znode Software Development Kit (SDK) projects for custom development and deploy them on a configured Azure Kubernetes Service (AKS) cluster (Znode-managed Azure environment). It eliminates the need for additional installations or setup during development in the downloaded SDK project.

Prerequisites

The following software is required to configure the Znode CLI. These third-party software components might request elevated system access if they are being installed for the first time:

Docker Desktop

Docker is a platform for developing and running applications within containers. Containers are portable and isolated environments that bundle an application and its dependencies, ensuring consistency across various environments.

To check the installed Docker version, use the following command:

docker --version



Docker Desktop is crucial for working with the Znode CLI. Without Docker, commands such as “deploy” will not function correctly, as they rely on Docker images stored in the AMLA repository.

Docker installation is optional when downloading the SDK using the “znode setup” command.

.NET (8.0)

The .NET Framework is required to execute Znode CLI commands. Commands will not run without this framework.

To check the installed version:

dotnet --version


Note: If the .NET Framework is not installed, the CLI will prompt the user to install it. If the user selects “Yes,” installation will proceed. Otherwise, it will be skipped.


Znode CLI Access Tokens / NuGet Credentials

Znode CLI Access Tokens / Nuget Credentials

Each customer (tenant) has designated users. The following credentials are required to set up the CLI:

  • Znode CLI Token (Per Developer Seat): Contact the Znode Support team to obtain a CLI token if not already available. The token is unique to each client user.
    • Example: Znode is a tenant and Joy.Jocab is a user for that tenant. A token can be generated for Joy under Znode.
    • Token Example: BiuL7AFvSJRU
  • Znode NuGet Access (Per Project): Contact the Znode Support team to acquire access to the Znode NuGet package repository.

Znode CLI: NuGet Source Configuration

To add the Znode CLI package source:

dotnet nuget add source "https://nuget.znode.com/nuget" -n "NugetZnode10xCLI" -u "<username>" -p "<password>" --store-password-in-clear-text
  • Username: A tenant user with NuGet access.
  • Password: The password of the above user.

Example:

dotnet nuget add source "https://nuget.znode.com/nuget" -n "NugetZnode10xCLI" -u "User1@Znode.com" -p "Password@123" --store-password-in-clear-text

Note:

  • To list available NuGet sources, use:
dotnet nuget list source
  • If the source already exists, remove it using:


dotnet nuget remove source <SourceName>

<SourceName> can be seen from the previous source list command.

Example:


Znode CLI: Znode NuGet Source Configuration

To add this source to the system:

Open the command prompt and enter the dotnet nuget add source command using the provided command.

Substitute the placeholders <username> and <password> with the authentic NuGet package source credentials, which can be obtained from the Znode administrator along with the Znode CLI access token.

Press Enter to execute the command.


Znode CLI: Installation

To install the Znode CLI tool:

dotnet tool install Znode.CLI -g

To upgrade to the latest version:

dotnet tool update Znode.CLI -g

To uninstall:

dotnet tool uninstall Znode.CLI -g


Znode CLI: Connect Command

Command syntax:

znode connect <token>


The connect command authenticates a developer using the CLI access token. Each token defines access to specific SDKs or environments.

  • Tokens may grant permissions to:
    • Set up only Webstore SDK
    • Set up only Custom API SDK
    • Set up both SDKs
  • Tokens may restrict deployment to specific environments (e.g., DEV, QA, PROD).
  • Each session remains valid for six hours. Once expired, re-authentication is required.


To retrieve token details:

znode connect info


Note:

  • Tokens are valid for one year from creation.
  • The session timeout is six hours.

Znode CLI Access Token Permissions Explained

The CLI access token used with the connect command (Explained above) has permissions based on the Developer Role.


SDK-Level Permission

Znode 10 provides three SDK permissions:

  • Webstore: For front-end developers working on Webstore customizations.
  • Custom API: For developers implementing business logic through APIs.
  • All: For developers working on both front-end and APIs.

Hosted Environment-Level Permission

Znode 10 hosts environments per tenant (e.g., Production, Stage, QA). Token permissions control deployment access. Some developers may have deployment access only to non-production environments.

Znode CLI: Setup Command

This command downloads the SDK project source and requires the security key already used during the CLI login.

To see available options:

znode setup -h


To execute setup:

znode setup


Notes:

  • The command must not be run from the root of a drive.
    • ✅ Valid: D:\dev\znode-10>
    • ❌ Invalid: C:\> or D:\> or directories with spaces like D:\dev\new folder>
  • After setup, configure the Webstore by:
    • Updating URLs in the .env file
    • Adding scripts in the package.json
    • Running initial commands:
npm i
npx nx dev webstore
npx nx dev page-builder
  • The command skips re-downloading source files if they already exist. Delete existing files or run the command in a new location for a fresh setup.

Znode CLI: Deploy Command

This command deploys the Webstore or Custom APIs SDK source code to the connected AKS environment.

Command:

znode deploy <SDKCode> <DeploymentEnvironment>


Examples:

znode deploy WebStoreSDK DEV
znode deploy CustomAPISDK DEV
  • Optional parameters: SourcePath and ReleaseFolderPath
  • For Webstore SDK, the ReleaseFolderPath is not required
  • The command confirms deployment details before proceeding
  • It validates token permissions for the selected SDK and environment


Notes:

  • The solution is built locally
  • An image is tagged using the current timestamp format: <ACRPath>/<ImageName>:<YYYYddMM>-<HHmmss>
  • The image is pushed to the ACR and deployed to AKS
  • If a Docker image error occurs, run:
docker pull <ACRServer>/<RepositoryName>:<image-tag>
  • Ensure CustomApiSDK and WebstoreSDK images are correctly defined in the docker-compose.yml file

Znode CLI: Update Copy Command

This command fetches the latest updates for Webstore and Custom API SDKs.

Command:

znode get-updated-copy


Notes:

  • Must be run within a project directory (not the root of a drive)
    • ✅ Valid: D:\dev\znode-10>
    • ❌ Invalid: C:\> or directories with spaces like D:\dev\new folder>

Znode CLI: Info/Error Logs

Logs are stored at:

%UserProfile%\AppData\Local\ZnodeCLILogs\


Note: Log paths may vary on macOS or other operating systems.

Queries and Remedies

Expired Token

If the token has expired and the znode connect info shows no setup details, rerun the znode setup command.

Znode CLI Installation Issues

Remove and re-add the NuGet source using valid credentials from the Znode administrator, as described in the NuGet configuration section.

WSL Resource Usage

If Windows Subsystem for Linux (WSL) is straining system resources:

  • Run:
    wsl --shutdown
  • Close Docker Desktop notification.
  • From the system tray, right-click Docker Desktop.
  • Click “Restart” and confirm in the popup.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.

Developer Quickstart Guides - V10