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

  • Options

  • 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

    • Subcommands for COS server administration

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] [OPTIONS] <SUBCOMMAND>

Flags

The following flags are available.

-h, --help

Prints help information.

-v, --version

Prints version information.

-v, --verbose

Verbose mode (-v, -vv, -vvv, etc.)

Options

The following option is available.

--log-path <log-path>

Set the logging directory into the registry. If the path is omitted the current setting will be retrieved from the registry. Internal HCA errors are logged at the location specified in the HCA.

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 previously requested tasks, fetched from the cache. Displays progress in 0-100%, rounded down. Specific GUIDs can also be passed in to retrieve the progress of specific tasks, in the form {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. By default the command displays the progress of each task until all tasks complete with or without error. The tool will exit with an error code if any of the tasks complete with error.

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 project 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.

Subcommands for COS server administration

The following subcommands are related to the server command, and can be used for COS server administration.

Note: The COS user name and password are required for these subcommands. These must be given in arguments cos-username and cos-password.

disjoin

Disjoin a project from COS. Works on both main site and satellite site. Removes the project from the hull admin and deletes its queue in the HCA. Does not remove any local or COS data.

find

Try to find a project in the COS database, and check if it is being used to store a Hull project.

help

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

info

Prints information regarding the COS server.

join

Join a project that is already present in COS. Works on both main site and satellite site. Will download any data that is checked out on this site. If the COS user name and password are omitted, the system will try to use Windows credentials.

recover

Recover a COS project from either a main or satellite site. This subcommand should be used if the file system is lost but the project data is still in COS. If the COS user name and password are omitted, the system will try to use Windows credentials.

register

Import/Create a project to an empty COS database. Only works on a main site.

update

Change the COS credentials of all COS servers in the hull administration that match the given host name/port combination. If one of the accounts is omitted, use the flags -cw or -nw to indicate that either the current account is a Windows account, or that the new account is a Windows account. Omitting both accounts will result in no changes since the command will change from Windows account to Windows account (accounts are equal).