Hull COS Client Command Line Interface (HCC CLI)

The Hull COS Client Command Line Interface (HCC CLI) is used to perform operations for managing HCA (Hull COS Agent), Hull projects, blocks and construction within a project, and COS servers.

The command line interface operates with commands which execute operations on various aspects of the Hull–COS system. Each command contains related subcommands which perform the actual operations. Subcommands can take optional flags or options, as well as any number of optional or mandatory arguments.

HCC CLI is an executable that is run in the Windows Command Prompt. The executable is hcc.exe, and it is located in the \nupashull\windowsNT\ncgbin subfolder in the CADMATIC Hull installation folder.

The hcc.exe executable can be called from batch files, following standard batch file conventions.

Refer to the following sections for detailed information:

• Overview

  • Built-in help

  • Notation conventions

• Notes
• Service Name

• Usage

  • Flags

  • Commands and subcommands

    • Subcommands for HCA administration

    • Subcommands for project administration

    • Subcommands for operations on blocks and construction

      • Subcommands for block operations

      • Subcommands for operations on construction

Overview

To use the command line interface, launch the hcc.exe executable, in the \nupashull\windowsNT\ncgbin subfolder in the CADMATIC Hull installation folder. Open the Windows Command Prompt at this location, and enter hcc at the command prompt. The interface will show basic usage information when launched.

Enter the desired command and subcommand with the possible flags, options an arguments.

Note: It is recommended to run the Command Prompt as administrator. Operations like installing or uninstalling HCAs and starting or stopping services only work if you run the Command Prompt as administrator.

Built-in help

The Hull COS Client Command Line Interface has a built-in help that provides brief information on the available commands and subcommands.

Running the help command lists all the available commands.

Each command contains its own help which gives a general description of it, as well as the flags, options, and arguments that can be used with it. The -h or --help flag can be used for the commands and subcommands. Examples:

• hcc projects add --help provides information on the add subcommand of the projects command.

• hcc hull block check-out -h provides information on the check-out subcommand.

Tip: Previously entered commands can be accessed by using the up and down arrow keys.

Notation conventions

Note the following notation conventions that are used in the HCC CLI built-in Help.

• < > A flag, option or argument enclosed in angle brackets is mandatory.

• [ ] A flag, option or argument enclosed in square brackets is optional.

• [env: VAR] Environment variable that is automatically used for a mandatory flag or argument.

• Items in the command line are separated by spaces.

• ... Signifies multiple. For example, <block_names>... indicates that one or more block names must be provided.

Notes

Consider the following notes.

• HCA ports – Only one process may listen to a given port. If you choose a port that is already taken, clients will not be able to connect to the HCA.

• Hostname – When installing an HCA, the hostname of the system will be detected.

Service name

The service name of an installed HCA agent will always have the HCA_ prefix.

When installing an HCA agent as a Windows service, or running an agent as console application, the system adds the prefix HCA_ to the specified HCA agent name if the name does not start with it.

There are the following additional requirements for the service name:

• The name without a prefix cannot be empty.

• The length of the full name, including the HCA_ postfix, cannot exceed 256 characters.

• The name may not contain any of the following characters: " * / \ ; < > ? ' ' (space).

Usage

The generic usage of the Hull COS Client Command Line Interface is as follows:

hcc [FLAGS] <SUBCOMMAND>

Flags

The following flags are available.

-h, --help

Prints help information.

-v, --version

Prints version information.

Commands and subcommands

The following top-level commands are available:

hca

HCA service operations

help

Prints a list of the available subcommands with a short explanation, or the help for the given subcommand(s).

hull

Hull operations

progress

Retrieve the progress of all requested tasks and wait for pending operations to complete, while displaying their progress.

projects

Project operations for managing projects in Hull

Subcommands for HCA administration

The following subcommands are related to the hca command and can be used for Hull COS Agent (HCA) administration.

canaccess

Check if the HCA has write access to the given directory.

help

Prints a list of the available subcommands with a short explanation, or the help for the given subcommand(s).

install

Install the HCA as a service and saves its information in the registry and in the hull administration. This command requires administrator rights to write in the registry and install the service.

ping

Ping an HCA service.

start

Start an installed HCA service. This command requires administrator rights to start the service.

stop

Stop an installed HCA service. Administrator rights are required to stop an HCA service.

uninstall

Uninstall the HCA and remove it from the services list. Administrator rights are required to write in the registry and uninstall the service.

Subcommands for project administration

The following subcommands are related to the projects command and can be used for Hull project administration.

add

Add a standalone (local) project to the Hull administration.

add-to-cos

Add Hull data to an existing COS database. The COS database should either contain no Hull data or contain a predefined Hull project. In the latter case, the project ID must be given. Hull data can be added on any site in the COS network.

add-to-site

Make Hull data available on this site from a COS server that contains Hull data. Any data that is checked out on this site will be downloaded.

help

Prints a list of the available subcommands with a short explanation, or the help for the given subcommand(s).

info

Displays all projects, and classifies them as standalone (local) or COS (distributed).

projects

Provides the full path of each project managed by the HCA.

recover-site

Recover a COS project from either a main or a satellite site. This subcommand can be used if the file system is lost but the project data is still in COS.

remove

Remove a standalone (local) project from the Hull project administration.

remove-site

Remove a Hull site from the project list and from the HCA, but the data remains untouched. This can be done on both a main site and a satellite site.

try-repair-partial-project-administration-conversion

When upgrading to 2023T2 or later, the Hull project administration is converted. If the conversion fails, because a user was still active in COS, this function can be used to try and correct the result.

Important: The HCA service must be stopped before attempting the repair!

Subcommands for operations on blocks and construction

The following subcommands are related to the hull command and can be used for operations on blocks and construction within blocks.

block

Perform operations on Hull block(s).

construction

Perform operations on only the construction within block(s).

help

Prints a list of the available subcommands with a short explanation, or the help for the given subcommand(s).

update-rfh-cache

Update the hole request cache in the project with the latest changes from COS. The project path can be passed with option --project-path or -p, and the Hullcentre path with option --hull-centre-path or -c.

Subcommands for block operations

The following subcommands are related to the block subcommand and can be used for block operations.

check-in

Check in block(s).

check-out

Check out block(s).

get

Get blocks.

help

Prints a list of the available subcommands with a short explanation, or the help for the given subcommand(s).

is-checked-out

For the specified project path and block name, print the string yes to standard output if that block is checked out to the site, and no otherwise. In case an error has occurred, the string. Error is printed to standard output, and details of the error are printed to standard error.

repair-state

Restore the checkout states of the block and the construction parts in the block. With this subcommand you can fix the problems in saving construction arising from the different checkout states of the hull block object and the parts belonging to the block. Enter hcc hull block repair-state -h at the command prompt for details of the usage.

save

Save blocks.

site

For the specified project path and block name, display the name of the site that has the block checked out on standard output, or None if no site has the block checked out. Note that the name of the main site will always be Main. In case an error has occurred, the string Error is printed to standard output, and details of the error are printed to standard error.

Subcommands for operations on construction

The following sub-commands are related to the construction sub-command and can be used for operations on construction.

get

Get construction.

help

Prints a list of the available subcommands with a short explanation, or the help for the given subcommand(s).

save

Save construction.