nuts stands for Network Updatable Things Services tool and is a portable package manager for java (mainly) that handles remote artifacts, installs these artifacts to the current machine and executes such artifacts on need.

nuts solves the fatjar problem delegating the dependency resolution to the time when the application is to be executed and simplifies the packaging process while being transparent to the build process. Actually, nuts uses maven pom descriptors to resolve dependencies when the artifact is installed on the target machine, and it can use also other types of descriptors for other types of packages.

nuts artifacts are stored into repositories. A repository may be local for storing local artifacts or remote for accessing remote artifacts (good examples are remote maven repositories). It may also be a proxy repository so that remote artifacts are fetched and cached locally to save network resources.

One manages a set of repositories called a workspace (like virtualenv in pip). Managed nuts (artifacts) have descriptors that depicts dependencies between them. This dependency is seamlessly handled by nuts (tool) to resolve and download on-need dependencies over the wire.

nuts is a swiss army knife tool as it acts like (and supports) maven build tool to have an abstract view of the artifacts dependency and like npm and pip language package managers to install and uninstall artifacts allowing multiple versions of the very same artifact to be installed. nuts is not exclusive for Java/Scala/Kotlin and other Java Platform Languages, by design it supports multiple artifact formats other than jars and wars and is able to select the appropriate artifacts and dependencies according to the current OS, architecture and even Desktop Environment.

nuts common verbs are:

• exec : execute an artifact or a command

• which : detect the proper artifact or system command to execute

• install, uninstall : install/uninstall an artifact (using its fetched/deployed installer)

• update,check-updates : search for updates

• deploy, undeploy : manage artifacts (artifact installers) on the local repositories

• fetch, push : download from, upload to remote repositories

• search : search for existing/installable artifacts

• welcome : a command that does nothing but bootstrapping nuts and showing a welcome message.

You'd still be Maven, yet you gonna be Nuts

When we recall that Java(TM) is the one language that has the more versatile number of libraries, frameworks and tools, I find it annoying not to have a decent package manager to make the leap and provide facilities I find prime in other languages and platforms (pip/python, npm/nodejs/javascript) and most of linux distribution (zypper/opensuse, dnf/redhat apt-get/debian/ubuntu)

Hence I'm introducing here a humble attempt to provide a tiny (300ko) yet powerful package manager for Java(TM) applications (but not only) that should handle jar files seamlessly (with little or no modification) and that comes with a set of portable tools that makes this management at a higher level. I'm not talking about redefining the wheel. I'm aware that many tools such as maven, are already very good at what they do, I just needed to make the leap for deployments. You will be able to deploy your applications without bundling all of their dependencies : nuts will take care of that.

So you'd still be maven, yet you gonna be nuts.

Nuts Package manager

nuts is actually :

• a transitive dependency resolution manager
• a package manager (backports maven and supports maven repositories)
• an automation tool
• a feature rich toolset
• an application framework
• decentralized
• sandbox based

Transitive dependency resolution manager

nuts calculates transitive dependencies of an application to resolve other packages to download at install or update/upgrade time. So typically, deployed applications should no more bundle their dependencies within the deployed archive. Thus we avoid the annoying fat jars (using maven plugins like 'maven-assembly-plugin' and 'maven-shade-plugin') and lib folders (using 'maven-dependency-plugin'). It will also reuse dependencies and packages across multiple installed applications and hence save disk space, and network bandwidth.

All what nuts needs is a descriptor file withing the jar file that defines the immediate dependencies. It then calculates all transitive dependencies automatically. And guess what, all maven built jars already contain that descriptor : the pom.xml file. So basically all maven applications are already nuts aware applications.

Package manager

nuts uses this dependency resolution to help install, update, remove and search for applications. To be able to use an application, it has to be installed and configured with all of its dependencies. This is the main goal of nuts. When we ask to install tomcat, for instance, it will search for the best version in registered repositories, download it, and configure it to be ready for execution. The best version is not always the the latest one. Actually it would be the latest valid one, thus the latest one that matches some constraints. Constraints include the version of the running java (tomcat 8 works on java 7 but not 6 for instance), the running operating system (windows, linux, ... to help selecting the proper binaries), may be the hardware architecture or even the operating distribution (for linux based systems). Constraints will filter the search result to include the best, the most accurate version to install. Installation also would configure the installed application and even may run another artifact to help this configuration.

nuts also handles search for newer versions and update the installed application at request. Updating a software does not necessarily delete the older version. Both version can coexist and it is up to the user the decide whether or not to retain both versions. Indeed, one of the key features of nuts is the ability to install and hence run multiple versions of the same software in parallel. You would never see an error message telling you can't install that software because a dependency of it is installed with different version. All software and all libraries can coexist peacefully.

Software artifacts are stored in repositories. nuts can handle multiple repositories, remote and local ones. Installed software are stored in special local repositories. Supported repositories include maven repositories and github repositories. Actually a fresh installation of nuts is configured with maven central repository so that, you already have access to thousands of installable artifacts.

Feature rich Toolset

nuts is intended to be used either by human users or by robots and other applications. It comes with portable, feature rich toolset, a versatile library and a handy parsable result.

nuts is mainly a commandline program that helps installing, uninstalling, searching, updating and running artifacts. To help desktop integration, nuts installs by default a set of other companion tools such as nsh (a portable bash-compatible implementation), and nadmin (an administration tool for nuts to configure users, authorizations, repositories, create scripts,...);

nsh brings the bash facilities to all environments (windows included) in a very portable manner. Besides it integrates well with the installed nuts version. Several common commands are ported to nsh such as cat,head, and ssh, as well as core features like pipes, redirection and scripts.

nadmin is intended for configuring nuts workspaces, managing repositories and users. It helps also configuring sub commands and aliases to make nuts usage even easier.

Nuts Workspaces

One of the key features of nuts is the ability to support multiple isolated workspaces, each managing it's own repositories, applications and libraries; each defining it's sandbox security constraints. Thus non-root installation is made easy while it remains possible to overlap between workspaces by sharing repositories. Roaming is also supported, so that a workspaces can be copied/moved across machines.

Application Framework

nuts can also be embedded as a library in you application. This enables you to wire classes on the fly by its network dependency-aware classloading mechanisms. The library allows as well building solid and well integrated applications, mainly console applications. Indeed, nuts comes with rich outputs that support automatic formatting to json, xml, table, tree and plain texts. It handles standard File Systems layouts; XDG Base Directory Specification is implemented for linux and MacOS. A compatible one is also implemented in Windows systems. And of course, it helps seamlessly install, update and remove events.

Nuts ? Really ?

In every palace you will find the wizard and the fool, the maven and the nuts; There's no exception in the java kingdom! If you do prefer acronyms here is another reason : nuts stands for Network Updatable Things Services. It should be able to facilitate things deployment and update over the wire where things resolve here to any piece of software depending (or not) on other piece of software.

Let's start the journey

Get started by running your first application. Nuts is not a build tool (like maven and gradle). Nuts is more likely to be compared with nodejs npm or python's pip

What you'll need

• java compatible operating system including [Linux],[Windows] and [MacOS]

• java version 1.8 or above. JRE is sufficient, JDK allows you to do more with nuts

java --version

But in the following example, I am assuming you are using a Linux distribution et MacOS. If you are using Windows please refer to the installation section.

Installing and Running Nuts

We start by opening a new terminal (term, konsole or whatever you prefer) then download nuts using this command : On linux/MacOS system we issue :

curl -sOL https://thevpc.net/nuts/nuts-stable.jar -o nuts.jar && java -jar nuts.jar -Zy

We used the flags -y to auto-confirm and -z to ignore cached binaries (combined here as -zy). These flags are optional and are used here to demonstrate some of Nuts' available options. The installation process may take several minutes, as it involves downloading all required dependencies, companions, and tools.

Welcome to nuts. Yeah, it is working...

nuts is well installed, just restart your terminal.

Now we will install jedit, a tremendous underrated text editor. So in your terminal type:

nuts install org.jedit:jedit

nuts jedit

As you can see, simple commands are all you need to download, install, configure and run jedit or any java application that is deployed in the maven repository.

So please visit nuts website or github repository for more information.

• Offline user documentation
• Nuts Rationale
• Nuts Components

• Nuts APIFeel free to explore these resources and dive deeper into what Nuts has to offer!

In this section we will consider the simplest usage of nuts package manager.

Running a deployed artifact

You can run any jar using nuts as far as the jar is accessible from one of the supported repositories. By default, nuts supports:

• maven central
• local maven folder (~/.m2)

Artifact Long Ids

nuts long ids are a string representation of a unique identifier of the artifact. It has the following form :

groupId:artifactId#version

for instance, to install (and run) netbeans-launcher (which is a simple UI helping launch of multiple instances of netbeans), you can issue

  nuts net.thevpc.app:netbeans-launcher#1.2.2

  nuts netbeans-launcher

In this form, nuts will auto-detect both the groupId and the version. The group id is detected if it is already imported (we will see later how to import a groupId). By default, there is a couple of groupIds that are automatically imported :

• .thevpc (contains various applications of the author)

• .thevpc.nuts.toolbox (contains various companion tools of nuts, such as nsh, ...)

And it turns out, hopefully, that netbeans-launcher belongs to an imported groupId, so we can omit it. Besides, if no version is provided, nuts will also auto-detect the best version to execute. If the application is already installed, the version you choose to install will be resolved. If you have not installed any, the most recent version, obviously, will be detected for you.

Artifact Installation

Any java application can run using nuts but it has to be installed first. If you try to run the application before installing it, you will be prompted to confirm installation. To install our favorite application here we could have issued :

  nuts install netbeans-launcher

Multiple Artifact version Installation

One of the key features of nuts is the ability to install multiple versions of the same application. We can for instance type :

  nuts install netbeans-launcher#1.2.2
  # then
  nuts install netbeans-launcher#1.2.0

  nuts netbeans-launcher#1.2.2 &
  # or
  nuts netbeans-launcher#1.2.0 &

  nuts netbeans-launcher &

Searching artifacts

  nuts search --installed

  nuts search --installed -l

I-X 2019-08-21 04:54:22.951 anonymous vpc-public-maven net.thevpc.app:netbeans-launcher#1.2.0
i-X 2019-08-21 04:54:05.196 anonymous vpc-public-maven net.thevpc.app:netbeans-launcher#1.2.2

The first column here is a the artifact status that helps getting zipped information of the artifact. the 'I' stands for 'installed and default' whereas, 'i' is simply 'installed'. The 'X' stands for 'executable application', where 'x' is simply 'executable'. Roughly said, executable applications are executables aware of (or depends on) nuts, as they provide a special api that helps nuts to get more information and more features for the application. As an example, executable applications have special OnInstall and OnUninstall hooks called by nuts. The second and the third columns are date and time of installation. The fourth column points to the installation user. When Secure mode has not been enabled (which is the default), you are running nuts as 'anonymous'. The fifth column shows the repository from which the package was installed. And the last column depicts the artifact long id.

Running local jar file with its dependencies

Let's suppose that my-app.jar is a maven created jar (contains META-INF/maven files) with a number of dependencies. nuts is able to download on the fly needed dependencies, detect the Main class (no need for MANIFEST.MF) and run the application. If a Main-Class Attribute was detected in a valid MANIFEST.MF, il will be considered. If more than one class is detected with a main method, nuts will ask for the current class to run.

When you run a local file, nuts will behave as if the app is installed (in the given path, an no need to invoke install command). Local files are detected if they are denoted by a valid path (containing '/' or '' depending on the underlying operating system). Dependencies will be downloaded as well (and cached in the workspace)

nuts ./my-app.jar some-argument-of-my-app

nuts --exec -Xms1G -Xmx2G ./my-app.jar argument-1 argument-2

GUI Installation

You can install nuts using a gui installer. Multiple targets are available. You may select a portable installer (a jar that you can double click as far as you have a valid java+ runtime installed and configured in your environment). You may also want to select a native image for the installer; you only need to download and run.

nuts comes with a dual version, stable and preview. Stable version is recommended in most cases. But if you want to take advantage of new features not yet released you may want to install the preview version.

The installer will even prompt you for selecting extra java applications you may want to install along with nuts. The only recommended apps are already selected and marked as Companions. This includes mostly nsh, a bash compatible implementation in Java.

Now the effective installation starts. You will see the progress in a colourful terminal.

And voilà! you now have reached the installation end. Just click on Exit.

If you check your system menu, you will notice some new icons, including a nuts aware terminal. On Linux and MacOs, you do not need such menu to run you favorite nuts command though. The Installer has already configured your shell rc files to include nuts in the execution PATH env variable.

Dark Mode

Your first commands

After installation, open any nuts aware terminal (on linux, any bash,zsh,fish,... terminal is ok).

$> nuts

$> nuts update

$> nuts search

$> nuts search 'net.thevpc.nuts.toolbox:*' --anywhere
 
        net.thevpc.nuts.toolbox:nsh#0.8.5.0
        net.thevpc.nuts.toolbox:ndoc#0.8.5.0
        net.thevpc.nuts.toolbox:ndexer#0.8.5.0
        net.thevpc.nuts.toolbox:njob#0.8.5.0
        net.thevpc.nuts.toolbox:nmvn#0.8.5.0
        net.thevpc.nuts.toolbox:nwork#0.8.5.0
        net.thevpc.nuts.toolbox:nsh#0.8.5.0
        net.thevpc.nuts.toolbox:ntomcat#0.8.5.0
        net.thevpc.nuts.toolbox:ntalk-agent#0.8.5.0
        net.thevpc.nuts.toolbox:ndiff#0.8.5.0
        net.thevpc.nuts.toolbox:nserver#0.8.5.0
        net.thevpc.nuts.toolbox:ndb#0.8.5.0
        net.thevpc.nuts.toolbox:nversion#0.8.5.0
        net.thevpc.nuts.toolbox:ncode#0.8.5.0
        net.thevpc.nuts.toolbox:ndocusaurus#0.8.5.0
        net.thevpc.nuts.toolbox:noapi#0.8.5.0

$> nuts install org.jedit:jedit

$> nuts jedit

$> nuts install njob

$> nuts update njob
 
$> nuts install netbeans-launcher

$> nuts netbeans-launcher
 

Running nuts in a containerized environment

If you want to run nuts in a containerized docker environment without creating a Dockerfile, you would run the following commands:

docker pull openjdk:8
docker run -it -v $(pwd):/workspace openjdk:8 sh

cd /workspace
wget https://thevpc.net/nuts/nuts-preview.jar -qO nuts.jar
java -jar nuts.jar -y <your-app>...

As an example here where you can run net.thevpc.nuts.toolbox:noapi#0.8.5.0 on your config file myrest-apis.json.

noapi is actually an OpenAPI documentation tool that generates a pdf file based on a opn api definition in JSON, YAML or TSON formats.

cd /workspace
wget https://thevpc.net/nuts/nuts-preview.jar -qO nuts.jar
java -jar nuts.jar -P=%s -ZyS net.thevpc.nuts.toolbox:noapi#0.8.5.0 myrest-apis.json

Creating your app Dockerfile

If you are willing to deploy your application in a docker isolated environment you can use this example pf Dockerfile

FROM openjdk:8
RUN wget https://thevpc.net/nuts/nuts-preview.jar -qO nuts.jar
RUN java -jar nuts.jar -Zy install <your application>
CMD java -jar nuts.jar -y <your application>
docker run -it -v $(pwd):/workspace openjdk:8 sh
cd /workspace
wget https://thevpc.net/nuts/nuts-preview.jar -qO nuts.jar
java -jar nuts.jar -P=no -ZyS -r=+thevpc net.thevpc.nuts.toolbox:noapi#0.8.5.0 buat-insurance-connector.json
#############

This is a docker file to run net.thevpc.nuts.toolbox:noapi an OpenAPI documentatation tool.

FROM openjdk:8
RUN wget https://thevpc.net/nuts/nuts-preview.jar -qO nuts.jar
RUN java -jar nuts.jar -Zy install net.thevpc.nuts.toolbox:noapi
CMD java -jar nuts.jar -y net.thevpc.nuts.toolbox:noapi

Installation of nuts in production is based on stable nuts binaries that are released according to a semi-annual schedule. Stable versions are deployed to maven-central and hence are made accessible very easily to all users. Releases include most of the time updates to the core nuts api (and bootstrap). Update/Fix releases can occur to fix blocking/serious/security issues is faster pace.

System Requirements

Here are all nuts requirements :

• Java : nuts requires a valid Java Runtime Environment (JRE) or Java Development Kit (JDK) version 8 or above to execute. Please note that you need to update your 1.8 version to the latest update (update 150+)

• System Memory: nuts memory footprint is very little and has no minimum RAM requirements.

• Disk: 5Mo on the disk are required for the nuts installation itself. In addition to that, additional disk space will be used for your local Nuts workspace. The size of your local workspace will vary depending on usage but expect at least 500MB.

• Operating System: nuts is able to run on any java enabled Operating System including all recent versions of Windows, Linux and MacOS.

java -version

$> java -version
java version "1.8.0_211"
Java(TM) SE Runtime Environment (build 1.8.0_211-b12)
Java HotSpot(TM) 64-Bit Server VM (build 25.211-b12, mixed mode)

Installation

• windows
• linux
• macos
• wget
• curl

java -jar nuts-0.8.5.jar  -Zy

$ wget https://thevpc.net/nuts/nuts-stable.jar -o nuts.jar
$ java -jar nuts.jar -Zy
$ exit

$ curl -sOL https://thevpc.net/nuts/nuts-stable.jar -o nuts.jar
$ java -jar nuts.jar -Zy
$ exit

$ curl -sOL https://thevpc.net/nuts/nuts-stable.jar -o nuts.jar
$ java -jar nuts.jar -Zy
$ exit

  $ wget https://thevpc.net/nuts/nuts-stable.jar -o nuts.jar
  $  java -jar nuts.jar -y

$ curl -sOL https://thevpc.net/nuts/nuts-stable.jar -o nuts.jar
$ java -jar nuts.jar -Zy
$ exit

As you can see, installation upon first launch, will also trigger installation of other optional programs called "companion tools". The main recommended helpful is nsh (stands for Nuts Shell), is a bash compatible shell implementation application that will run equally on linux and windows systems.

Test Installation

nuts --version

0.8.5/0.8.5.0

Run a command

To run a command using nuts just type

nuts <command>

Installation of nuts for preview/test/evaluation or simply for personal use is based on a rolling nuts binaries version that is released a faster pace than the production version (generally a semi-monthly schedule). Versions are not rock solid but still they are "very" usable and more importantly they include all latest features. Preview releases are deployed to a development repository and hence are made accessible using a repository swith option.

System Requirements

Here are all nuts requirements :

• Java : nuts requires a valid Java Runtime Environment (JRE) or Java Development Kit (JDK) version 8 or above to execute. Please note that you need to update your 1.8 version to the latest update (update 150+)

• System Memory: nuts memory footprint is very little and has no minimum RAM requirements.

• Disk: 5Mo on the disk are required for the nuts installation itself. In addition to that, additional disk space will be used for your local Nuts workspace. The size of your local workspace will vary depending on usage but expect at least 500MB.

• Operating System: nuts is able to run on any java enabled Operating System including all recent versions of Windows, Linux and MacOS.

java -version

$ java -version
java version "1.8.0_211"
Java(TM) SE Runtime Environment (build 1.8.0_211-b12)
Java HotSpot(TM) 64-Bit Server VM (build 25.211-b12, mixed mode)

Installation

• windows
• linux
• macos
• wget
• curl

java -jar nuts-preview.jar -Zy

$ wget https://thevpc.net/nuts/nuts-preview.jar -qO nuts.jar
$ java -jar nuts.jar -r=+preview -Zy
$ exit

$ curl -sOL https://thevpc.net/nuts/nuts-preview.jar -o nuts.jar
$ java -jar nuts.jar -Zy
$ exit

$ wget https://thevpc.net/nuts/nuts-preview.jar -qO nuts.jar
$ java -jar nuts.jar -r=+preview -Zy
$ exit

$ curl -sOL https://thevpc.net/nuts/nuts-preview.jar -o nuts.jar
$ java -jar nuts.jar -r=+preview -Zy
$ exit

As you can see, installation upon first launch, will also trigger installation of other optional programs called "companion tools". The main recommended helpful is nsh (stands for Nuts Shell), is a bash compatible shell implementation application that will run equally on linux and windows systems.

Test Installation

nuts --version

0.8.5/0.8.5.0

Run a command

To run a command using nuts just type

nuts <command>

recover mode

recover mode will apply best efforts to correct configuration without losing them. It will delete all cached data and libraries for them to be downloaded later and searches for a valid nuts installation binaries to run (it will actually do a forced update). To run nuts in recover mode type :

nuts -z

newer mode

newer mode will apply best efforts to reload cached files and libraries. to run nuts in 'newer mode' type:

nuts -N

reset mode

reset mode will apply all efforts to correct configuration by, actually, deleting them (and all of workspace files!!) to create a new fresh workspace. This is quite a radical action to run. Do not ever invoke this unless your are really knowing what you are doing. To run nuts in reset mode type :

nuts -Z

hard-reset mode

hard-reset mode will delete all nuts configuration files including all workspaces. This is quite a radical action to run. Do not ever invoke this unless your are really knowing what you are doing. To run nuts in reset mode type :

nuts --hard-reset

kill mode

kill mode is a special variant of reset mode where workspace will not be recreated after deletion. This can be achieved by using a combination of reset mode and --skip-boot (-Q) option. Do not ever invoke it unless you are really knowing what you are doing. To run nuts in kill mode type :

nuts -ZQ

nuts -Q --hard-reset

After invoking reset mode

java -jar nuts.jar

nuts net.thevpc.toolbox.nsh:nsh#0.8.5.0

Imports

nuts net.thevpc.toolbox.nsh:nsh#0.8.5.0
# becomes
nuts settings add import net.thevpc.toolbox
# now call it simply with
nuts nsh#0.8.5.0
# or even simpler with
nuts nsh

Aliases

Aliases help you define your own command by calling existing artifacts and defining some arguments as well. It is very similar to shell aliases where you define ll as an alias to /bin/ls -l for example.

nuts net.thevpc.toolbox.nsh:nsh#0.8.5.0
# becomes
nuts settings add alias ll='net.thevpc.toolbox.nsh:nsh#0.8.5.0 -c ls -l'
# now call it simply with
nuts ll

Launchers

nuts net.thevpc.toolbox.nsh:nsh#0.8.5.0
# becomes
nuts settings add launcher --menu --desktop 'net.thevpc.toolbox.nsh:nsh#0.8.5.0'
# now call it simply click on the desktop icon or open via system menu

nuts has been designed and implemented with automation and devops philosophy in mind.

nuts Application Framework infrastructure provides a seamless support process automation with structured output, including json, xml, yaml, tson and so on. You can for instance call the POSIX ls command and get the file list as json. You can then process this json

Install Automation

Structured Output

Environment Sensitive

Multi Platform

Workspace Isolation

Security Mechanisms

nuts supports a specific format for command line arguments. This format is the format supported in nuts Application Framework (NAF) and as such all NAF applications support the same command line arguments format. Arguments in nuts can be options or non options. Options always start with hyphen (-).

Short vs Long Options

Valued / Non-valued Options

nuts -w=/myfolder/myworkspace
nuts -w /myfolder/myworkspace
nuts --workspace /myfolder/myworkspace
nuts --workspace=/myfolder/myworkspace

Boolean Options

To define a "false" value to the boolean option we can either suffix with "=false" or prefix with "!" or "~" sign. Hence, "--install-companions=false", "--!install-companions" and "--~install-companions" are all equivalent. Note also that ~ if referred to ! because in bash shells (and som other shells) ! will be expanded in a special manner.

Combo Simple Options

Ignoring Options, Comments

Nuts Option Types

Options in nuts are can be of one of the following categories :

• Create Options : such options are only relevant when creating a new workspace. They define the configuration of the workspace to create. They will be ignored when the workspace already exists. They will be ignored too, in sub-processes. Examples include
  • --install-companions
  • --archetype
  • --store-strategy
  • --standalone
• Runtime Options : such options are relevant when running a workspace (be it existing or to be created) and are not passed to sub-processes
  • --reset
  • --recover
  • --dry
  • --version

• Exported Options : are passed to sub-nuts-processes that will be created by nuts. For instance when nuts will call the nsh command it will spawn a new process. In such case, these options are passed to the sub-process as environment variable.

  • --workspace
  • --global
  • --color
  • --bot
• Executor Options : are options that are supported byte the package executor. Most of the time this will be the java executor and hence this coincides with the JVM options)
  • -Xmx...
  • -Xmx
  • -D...

• Custom Nuts options : are special nuts options that are specific to nuts implementation or validation process to be promoted to standard options. The arguments parser will never report an error regarding such options. They are used when available and valid. they will be ignored in all other cases. Such options start with triple hyphen (---)

  • ---monitor.enabled
  • ---monitor.start
  • ---show-command
  • ---perf
  • ---init-platforms
  • ---init-scripts
  • ---init-java
  • ---system-desktop-launcher
  • ---system-menu-launcher
  • ---system-custom-launcher
• Application Options : are options that are by default supported by Applications using NAF (Nuts Application Framework) (as well as Nuts it self).
  • --help
  • --version

all nuts options are described in the command help. Just type :

nuts --help

is largely inspired by XDG Base Directory Specification and hence defines several store locations for each file type. Such organization of folders is called Layout and is dependent on the current operating system, the layout strategy and any custom configuration.

Store Locations

nuts File System defines the following folders :

• config : defines the base directory relative to which application specific configuration files should be stored.

• apps : defines the base directory relative to which application executable binaries should be stored

• lib : defines the base directory relative to which application non executable binaries should be stored

• var : defines the base directory relative to which application specific data files (other than config) should be stored

• log : defines the base directory relative to which application specific log and trace files should be stored

• temp : defines the base directory relative to which application specific temporary files should be stored

• cache : defines the base directory relative to which application non-essential data and binary files should be stored to optimize bandwidth or performance

• run : defines the base directory relative to which application-specific non-essential runtime files and other file objects (such as sockets, named pipes, ...) should be stored

nuts defines such distinct folders (named Store Locations) for storing different types of application data according to your operating system.

• apps : "$HOME/AppData/Roaming/nuts/apps"
• lib : "$HOME/AppData/Roaming/nuts/lib"
• config : "$HOME/AppData/Roaming/nuts/config"
• var : "$HOME/AppData/Roaming/nuts/var"
• log : "$HOME/AppData/Roaming/nuts/log"
• temp : "$HOME/AppData/Local/nuts/temp"
• cache : "$HOME/AppData/Local/nuts/cache"
• run : "$HOME/AppData/Local/nuts/run"

• config : "$HOME/.config/nuts"
• apps : "$HOME/.local/share/nuts/apps"
• lib : "$HOME/.local/share/nuts/lib"
• var : "$HOME/.local/share/nuts/var"
• log : "$HOME/.local/log/nuts"
• cache : "$HOME/.cache/nuts"
• temp : "$java.io.tmpdir/$username/nuts"
• run : "/run/user/$USER_ID/nuts"

home/me/.config/nuts/default-workspace/config/id/net/vpc/app/netbeans-launcher/1.2.4/

C:/Users/me/AppData/Roaming/nuts/log/nuts/personal/config/id/net/vpc/app/netbeans-launcher/1.2.4/app.log

Store Location Strategies

When you install any application using the nuts command a set of specific folders for the presented Store Locations are created. For that, two strategies exist : Exploded strategy (the default) and Standalone strategy.

In Exploded strategy nuts defines top level folders (in linux ~/.config for config Store Location etc), and then creates withing each top level Store Location a sub folder for the given application (or application version to be more specific). This helps putting all your config files in a SSD partition for instance and make nuts run faster. However if you are interested in the backup or roaming of your workspace, this may be not the best approach.

The Standalone strategy is indeed provided mainly for Roaming workspaces that can be shared, copied, moved to other locations. A single root folder will contain all of the Store Locations.

home/me/.config/nuts/default-workspace/config/id/net/vpc/app/netbeans-launcher/1.2.4/

/home/me/.config/nuts/default-workspace/log/id/net/vpc/app/netbeans-launcher/1.2.4/

/home/me/.config/nuts/default-workspace

whereas in the Exploded strategy the Store Location are "exploded" into multiple root folders.

Custom Store Locations

Selecting strategies

nuts -w my-workspace --exploded

nuts -w my-workspace --standalone

Finer Customization

nuts -w my-workspace --system-conf-home=/myssd/myconfig

nuts help

Nuts Text Format

nuts comes up with a simple coloring syntax that helps writing better looking portable command line programs. standard output is automatically configured to accept the "Nuts Text Format" (NTF) syntax. Though it remains possible to disable this ability using the --!color standard option (or programmatically, see nuts API documentation). NTF will be translated to the underlying terminal implementation using ANSI escape code on linux/windows terminals if available.

Nuts Text Format Specification

<TOKEN> S10: '##########'
<TOKEN> S9 : '#########'
<TOKEN> S8 : '########'
<TOKEN> S7 : '#######'
<TOKEN> S6 : '######'
<TOKEN> S5 : '#####'
<TOKEN> S4 : '####'
<TOKEN> S3 : '###'
<TOKEN> S2 : '##'
<TOKEN> S1 : '##'
<TOKEN> A3 : '\```'

<RULE>  S2 ':' KEY ':' ANYTHING S2
<RULE>  S2 '{:' WORD ANYTHING S2
<RULE>  13 ANYTHING A3

• welcome : this is the default command that simply shows a welcome message and exits

• help : documentation and help command for nuts and applications and exits

• version : show nuts version and exits

• info : show detailed nuts installation information and exits

• license : simply show nuts license and exits

• search : search for applications installed/to install

• fetch : download applications (without installing)

• which : resolve the appropriate application (or an internal command) for a given command

• exec : execute c(or an internal command)

• install : installs an application

• uninstall : uninstalls an application

• update : updates an installed application

• reinstall : reinstall an existing application

• check-updates : checks for updates of an application (do not perform the update)

• deploy : deploys a local application (and its descriptors) to a local repository

• push : syncronizes the local repositry to it's remote peer and hence, deploy to a remote repository.

• bundle : creates a standalone bundle as a complete nuts workspace that serve a single application

• settings : this is main settings/configuration commands to manage nuts workspaces, apps, security, etc.

exec command runs another command and which command does a dry run of it.

nuts netbeans-command

nuts exec netbeans-command

me@linux:~> nuts exec -Xmx1G netbeans-launcher

Here we pass -Xmx1G option argument to java executor because netbeans-launcher will be resolved as a java based artifact. For what concerns which command, it does not really execute the command, it just resolves the command execution

me@linux:~> nuts which version ls
version : internal command 
ls : nuts alias (owner maven-local://net.thevpc.app.nuts.toolbox:nsh#0.8.5.0 ) : maven-local://net.thevpc.app.nuts.toolbox:nsh#0.8.5.0 -c ls

Here which returns that version is an internal command while ls is an alias to an artifact based command (nsh -c ls) which is called a "nuts alias". As you can see, ls is actually a sub command of nsh artifact.

1.2 External Commands

nuts netbeans-command

1.2 External Files & URLs

You can run any jar file using nuts as far as it fulfills two points : the files must contain a supported descriptor (if it is compiled with maven, it already has the supported descriptor) and the file should be typed as a path (it must contain a '/' or '' separator)

wget -N https://github.com/thevpc/vpc-public-maven/raw/master/net/vpc/app/netbeans-launcher/1.2.2/netbeans-launcher-1.2.2.jar
nuts ./netbeans-launcher-1.2.2.jar

nuts https://github.com/thevpc/vpc-public-maven/raw/master/net/vpc/app/netbeans-launcher/1.2.2/netbeans-launcher-1.2.2.jar

2. Execution types

2.1 spawn

me@linux:~> nuts --spawn ls

2.2 embedded

me@linux:~> nuts --embedded ls

2.3 syscall

me@linux:~> nuts --syscall ls

3 Execution modes

3.1 effective execution

3.2 dry execution

me@linux:~> nuts --dry version
[dry] internal version 

execute a command
    runs command with the given executor options ( it will be considered an option if it
    starts with '-' ). This is helpful to issue JVM Options to executor for instance

##)  
SYNOPSIS:



    nuts exec [<-options>]...  ...
         --exec [<-options>]...  ...
         -e [<-options>]...  ...

##)  
OPTIONS:



    --embedded | -bsh
        when invoking a nuts artifact, it will be executed in the current process (no JVM process wil be spawn)

    --external | --spawn or -xsh
        when invoking a nuts artifact, it will always be executed in a newly created
        process (this is the default)

    --system
        the command is considered as a native command (not a nuts) and will be passed
        to the os as is.

    --root-cmd
        the command is considered as a native command (not a nuts) and will be passed
        to the os as is with root privileges (a password will be asked for).

    --target=
        the command is run on a remote machine using the given connexion string.
        The current version supports ssh connexion strings in the following form
        'ssh://username:password@address:port'.
        When the username is not provided, the current user is considered.
        When the password is not provided, the default ssh key is used.
        When the port is not provided, 22 port number is considered.

    --current-user
        when using a system command, the command is run with the current user privileges (default).

    --as-root
        when using a system command, the command is run with the system root privileges. credentials may be asked for.

    --as-user=
        when using a system command, the command is run with the given system username privileges. credentials may be asked for.

    --open-file
        the path to execute will not be executed. Instead it will be opened with assigned editor. System bindings are most likely to be considered.



##)  
EXAMPLES



    nuts exec --help
        show this help and exit

    nuts exec --yes -e -Xmx1G netbeans-launcher
        runs netbeans-launcher with JVM option -Xmx1G. If the artifact is not installed
        it will be automatically installed ( --yes modifier helps bypassing interactive mode)

    nuts exec my-nuts-group:my-nuts#12.3
        executes the version 12.3 of my-nuts-group:my-nuts

    nuts exec my-nuts-group:my-nuts
        executes the latest version of my-nuts-group:my-nuts

    nuts exec my-nuts
        executes the latest version of my-nuts-group:my-nuts supposing that my-nuts-group
        is added as imported group using config import my-nuts-group

    nuts -ZSby -w test ./build-website.nsh 
        run sh file

    nuts -Zy -w test /home/vpc/target/hl/local.vpc-no-name-1.0.0-SNAPSHOT.jar 
        run jar file

    nuts --verbose -ZSbkKy -w=test6 tn.corp.mlda:mlda 
        run javafx app

    nuts -ZykKS -w=temp --verbose exec --main-class=1 org.springframework.boot:spring-boot-cli#2.4.1 
        run spring boot cli

which command does a dry run of a command.

nuts netbeans-command

nuts exec netbeans-command

me@linux:~> nuts exec -Xmx1G netbeans-launcher

Here we pass -Xmx1G option argument to java executor because netbeans-launcher will be resolved as a java based artifact. For what concerns which command, it does not really execute the command, it just resolves the command execution

me@linux:~> nuts which version ls
version : internal command 
ls : nuts alias (owner maven-local://net.thevpc.app.nuts.toolbox:nsh#0.8.5.0 ) : maven-local://net.thevpc.app.nuts.toolbox:nsh#0.8.5.0 -c ls

Here which returns that version is an internal command while ls is an alias to an artifact based command (nsh -c ls) which is called a "nuts alias". As you can see, ls is actually a sub command of nsh artifact.

1.2 External Commands

nuts netbeans-command

1.2 External Files & URLs

You can run any jar file using nuts as far as it fulfills two points : the files must contain a supported descriptor (if it is compiled with maven, it already has the supported descriptor) and the file should be typed as a path (it must contain a '/' or '' separator)

wget -N https://github.com/thevpc/vpc-public-maven/raw/master/net/vpc/app/netbeans-launcher/1.2.2/netbeans-launcher-1.2.2.jar
nuts ./netbeans-launcher-1.2.2.jar

nuts https://github.com/thevpc/vpc-public-maven/raw/master/net/vpc/app/netbeans-launcher/1.2.2/netbeans-launcher-1.2.2.jar

2. Execution types

2.1 spawn

me@linux:~> nuts --spawn ls

2.2 embedded

me@linux:~> nuts --embedded ls

2.3 syscall

me@linux:~> nuts --syscall ls

3 Execution modes

3.1 effective execution

3.2 dry execution

me@linux:~> nuts --dry version
[dry] internal version 

resolves commands type

##)  
SYNOPSIS:



    nuts which [<-options>]... [] ...
        resolves commands type



##)  
EXAMPLES:



    nuts which --help
        show this help and exit

    nuts which netbeans-launcher exec
        show netbeans-launcher and exec types. The first is a artifact the latter is an internal command

fetch command is used to download content of an artifact when you exactly know of it's nuts long id (which is required). This will download a cached version of the artifact in the local machine (the artifact passes to 'fetched' status)

me@linux:~> nuts fetch net.thevpc.app:netbeans-launcher#1.2.2

search for artifacts

##)  
SYNOPSIS:



    nuts search [<-options>]...  ...  ...
        search for 

##)  
OPTIONS:



    --lenient
        when an id is found but its descriptor and/or its file are not found, do not raise an error and continue. default no

    --all-versions
        return all versions of the same ids. if no will always return the latest one. default yes

    --duplicates
        return the same version from distinct repositories if found. default yes

    --distinct
        remove duplicates . default false

    -L | --latest | --latest-versions
        return latest version of each searched id. equivalent to --all-versions=no

    -S | --single | --single-versions
        return one instance of each version even if found in distinct repositories. equivalent to --duplicate=no

    -s | --sort
        sort result. default no

    --main
        include main result. This is meaningful when one needs to find only dependencies, and hence turns this flag to no. default yes

    --dependencies
        include dependencies in result. default no

    --main-only
        include main result and no dependencies. equivalent to --main=yes --dependencies=no

    --dependencies-only
        include dependencies and no main. equivalent to --main=no --dependencies=no

    --main-and-dependencies
        include main result and no dependencies. equivalent to --main=yes --dependencies=yes

    -r | --repository 
        include repository in the search process. if none defined, all repositories are searched.

    --arch x86|amd64|ia64|ppc|sparc
        include architecture in the search process. if none defined, all architectures are searched.

    --packaging jar|war|...
        include packaging in the search process. if none defined, all packagings are searched.

    --cached
        include cached in the search process. default yes

    --indexed
        include search index in the search process. default yes

    --effective
        compute effective descriptor. default no

    --content
        include content. default no

    --install-info
        include install information. default false

    --location
        force found contents to be copied to location

    -f | --fetch offline|online|anywhere|installed|remote
        include fetch mode in the search process. if none defined, all fetch modes are searched.

    --offline | -F 
        equivalent to --fetch=offline

    --online | -O
        equivalent to --fetch=online

    --anywhere | -a
        equivalent to --fetch=anywhere

    --installed | -i 
        search for installed only packages

    --included
        search for included packages in other installations

    --deployed
        search for installed and required (as dependencies) packages

    --remote | -R
        equivalent to --fetch=remote

    --optional
        relevant when --dependencies is armed.
        --optional=     : search for all dependencies, including optional (default)
        --optional=yes  : search for optional dependencies only
        --optional=no   : search for non optional dependencies only

    --scope api|implementation|compile|provided|import
               |runtime|system|test-compile|test-provided
               |test-runtime|test|run|run-test|other|all
        relevant when --dependencies is armed.
        include scope in the search dependencies process.
        if none defined, only run scope is searched.

    --default | --default-versions
        find only default installed versions. This is meaningful with --installed flag

    --libs | --lib
        find libraries (non app) only

    --apps | --app
        find applications (non libraries) only

    --nuts-apps |--nuts-app
        find nuts applications only

    --extensions | --extension
        find extensions only

    --runtime
        find nuts runtime only

    --companions | --companion
        find companions only

    --api-version
        find artifacts compatible with the given api-version

    -l
    --long
    --display-long
        equivalent to --display=long

    --display=
        define columns to display (ordered list of columns, comma separated)
        Accepted columns are:
            status             : show nuts status using condensed format using 3 characters
                char #1 : show installation status
                    I : means 'installed' and is 'default'
                    i : means 'installed' and is not default
                    d : means 'dependency' (aka 'required') locally deployed
                    f : means 'fetched' locally but not installed
                    r : means 'remote' (not fetched)
                char #2 : show package type
                    a : nuts 'api' package
                    r : nuts 'runtime' package
                    e : nuts 'extension' package
                    c : nuts 'companion' package
                    - : other package
                char #3 : show application status
                    X : means executable nuts application (implementing NutsApplication)
                    x : means executable regular application
                    - : means non executable or unknown
                char #4 : show scope status (when applicable)
                    c : compile/api scope
                    i : implementation scope
                    r : runtime scope
                    s : system scope
                    p : provided scope
                    t : test (any) scope
                    m : import scope
                    O : other
                    - : unknown
            install-date       : artifact install date
            install-user       : artifact install user
            id                 : artifact id
            name               : simple name
            packaging          : artifact packaging (jar, war, msi, exe, ...)
            arch               : artifact supported architectures (x86, x64,...)
            platform           : artifact supported platforms (java, dotnet, ...)
            os                 : artifact supported operation systems (Linux, Windows,...)
            osdist             : artifact supported OS distributions (OpenSuSE, Ubuntu, ...)
            de                 : artifact supported OS Desktop Environment (KDE, GNOME,...)
            exec-entry         : Main class
            file-name          : artifact file name
            file               : artifact file path
            var-location       : artifact var folder
            temp-location      : artifact temp folder
            config-location    : artifact config folder
            lib-location       : artifact lib folder
            log-location       : artifact log folder
            cache-location     : artifact cache folder
            programs-location  : artifact programs folder
            run-location       : artifact run folder
            long               : equivalent to status, install-date, install-user, id
            all                : equivalent to all of the above

    --omit-env
        when formatting id, omit env

    --omit-face
        when formatting id, omit face

    --omit-group
        when formatting id, omit group

    --omit-imported-group
        when formatting id, omit imported group

    --omit-repo
        when formatting id, omit repository

    --highlight-imported-group
        when formatting id, highlight imported group

    --highlight-optional
        when formatting id, highlight optional

    --highlight-scope
        when formatting id, highlight scope



##)  
EXAMPLES



    nuts search --help
        show this help and exit

    nuts search
        search installed nuts

    nuts search --offline netbeans-*
        search all artifacts that start with "netbeans-" in all local repositories

    nuts search --anywhere netbeans-*
        search all artifacts that start with "netbeans-" in all local and remote repositories

    nuts -Zy -w test search --repository spring 
        search using spring repository only

    -Zy search -l --json 
        search locally installed artifacts in json format

A part from URL and path based executions, an artifact should be installed to be run. Installation can be auto fired when you first execute the artifact (you will be prompted to install the artifact) or manually using the install command. Note that when you run directly a jar file as a path or url, the artifact will not be installed! to install an application just type

nuts install <your-artifact-query-here>

nuts install net.thevpc.app:netbeans-launcher#1.2.2

nuts install net.thevpc.app:netbeans-*

nuts install net.thevpc.app:netbeans-launcher#1.2.2
#this second time we have to force install
nuts install -- force net.thevpc.app:netbeans-launcher#1.2.2

me@linux:~> nuts install net.thevpc.app:netbeans-launcher#1.2.2
me@linux:~> nuts netbeans-launcher
1.2.2
me@linux:~> nuts install net.thevpc.app:netbeans-launcher#1.2.1
me@linux:~> nuts netbeans-launcher
1.2.1
me@linux:~> nuts install net.thevpc.app:netbeans-launcher#1.2.2
1.2.2

Purpose

• A+B : read A main package and B dependencies
• A+B? : ask, if confirmed, read A main package and B dependencies.
• require : deploy package as 'required'
• install : deploy package as 'installed'
• nothing : do nothing

• require : install the package and all of its dependencies as required class installed package
• install : install the package and all of its dependencies as first class installed package
• reinstall : re-install or re-required the package and all of its dependencies
• repair : repair (re-install or re-required) the given dependency

install nuts package 

##)  
SYNOPSIS:



    nuts install <-options> ...

##)  
OPTIONS:



    -c | --companions
        include companions in the install process

    -i | --installed
        include already installed artifacts in the install process (re-install)

    -g | --args  ...
        pass the given args to the install executor



##)  
EXAMPLES:



    nuts install --help
        show this help and exit

    nuts install netbeans-launcher
        install netbeans-launcher

    nuts --debug -Zy -w test install pnote
        install pnote in debug mode

    nuts -Zyb -w test --verbose install netbeans-launcher
        install netbeans-launcher in verbose mode

A part from URL and path based executions, an artifact should be installed to be run. Installation can be auto fired when you first execute the artifact (you will be prompted to install the artifact) or manually using the install command. Note that when you run directly a jar file as a path or url, the artifact will not be installed! to install an application just type

nuts install <your-artifact-query-here>

nuts install net.thevpc.app:netbeans-launcher#1.2.2

nuts install net.thevpc.app:netbeans-*

nuts install net.thevpc.app:netbeans-launcher#1.2.2
#this second time we have to force install
nuts install -- force net.thevpc.app:netbeans-launcher#1.2.2

me@linux:~> nuts install net.thevpc.app:netbeans-launcher#1.2.2
me@linux:~> nuts netbeans-launcher
1.2.2
me@linux:~> nuts install net.thevpc.app:netbeans-launcher#1.2.1
me@linux:~> nuts netbeans-launcher
1.2.1
me@linux:~> nuts install net.thevpc.app:netbeans-launcher#1.2.2
1.2.2

Purpose

• A+B : read A main package and B dependencies
• A+B? : ask, if confirmed, read A main package and B dependencies.
• require : deploy package as 'required'
• install : deploy package as 'installed'
• nothing : do nothing

• require : install the package and all of its dependencies as required class installed package
• install : install the package and all of its dependencies as first class installed package
• reinstall : re-install or re-required the package and all of its dependencies
• repair : repair (re-install or re-required) the given dependency

uninstall nuts package 

##)  
SYNOPSIS:



    nuts uninstall ...  ...
        uninstall one or more nuts from repositories if installed.
        if no nuts-id is defined an error will occur

##)  
OPTIONS:



    -e | --erase
        enable erase mode to delete all of artifact's config data as well

     ...
        provide arguments to pass to uninstaller



##)  
EXAMPLES



    nuts uninstall --help
        show this help and exit

    nuts uninstall netbeans-launcher
        uninstall netbeans-launcher

    nuts uninstall my-group:my-thing#2.3
        uninstalls - if able to resolve it - exactly the nuts "my-group:my-thing#2.3"

    nuts uninstall my-group:my-thing
        uninstalls - if able to resolve it - the latest version of "my-group:my-thing"

    nutsuninstall my-thing
        uninstalls - if able to resolve it - the latest version of "my-group:my-thing" as long as "my-group" is defined as a default import group

A part from URL and path based executions, an artifact should be installed to be run. Installation can be auto fired when you first execute the artifact (you will be prompted to install the artifact) or manually using the install command. Note that when you run directly a jar file as a path or url, the artifact will not be installed! to install an application just type

nuts install <your-artifact-query-here>

nuts install net.thevpc.app:netbeans-launcher#1.2.2

nuts install net.thevpc.app:netbeans-*

nuts install net.thevpc.app:netbeans-launcher#1.2.2
#this second time we have to force install
nuts install -- force net.thevpc.app:netbeans-launcher#1.2.2

me@linux:~> nuts install net.thevpc.app:netbeans-launcher#1.2.2
me@linux:~> nuts netbeans-launcher
1.2.2
me@linux:~> nuts install net.thevpc.app:netbeans-launcher#1.2.1
me@linux:~> nuts netbeans-launcher
1.2.1
me@linux:~> nuts install net.thevpc.app:netbeans-launcher#1.2.2
1.2.2

Purpose

• A+B : read A main package and B dependencies
• A+B? : ask, if confirmed, read A main package and B dependencies.
• require : deploy package as 'required'
• install : deploy package as 'installed'
• nothing : do nothing

• require : install the package and all of its dependencies as required class installed package
• install : install the package and all of its dependencies as first class installed package
• reinstall : re-install or re-required the package and all of its dependencies
• repair : repair (re-install or re-required) the given dependency

check for updates
    check if a newer version of nuts is available in the current workspace without performing updates

##)  
SYNOPSIS



    nuts check-updates [<-options>]...  ...

##)  
OPTIONS:



    -a | --all
        check updates for both workspace's api, runtime extensions and installed artifacts

    -w | --ws or --workspace
        check updates for all workspace's related artifacts (api, runtime and extensions)

    -i | --installed
        check updates for all installed artifacts

    -e | --extensions
        check updates for all workspace's extensions

    -r | --runtime
        check updates for workspace's runtime artifact (minor workspace update)

    -A | --api
        check updates for workspace's api (major workspace update)



##)  
EXAMPLES



    nuts check-updates --help
        show this help and exit

    nuts check-updates
        check updates for current workspace

A part from URL and path based executions, an artifact should be installed to be run. Installation can be auto fired when you first execute the artifact (you will be prompted to install the artifact) or manually using the install command. Note that when you run directly a jar file as a path or url, the artifact will not be installed! to install an application just type

nuts install <your-artifact-query-here>

nuts install net.thevpc.app:netbeans-launcher#1.2.2

nuts install net.thevpc.app:netbeans-*

nuts install net.thevpc.app:netbeans-launcher#1.2.2
#this second time we have to force install
nuts install -- force net.thevpc.app:netbeans-launcher#1.2.2

me@linux:~> nuts install net.thevpc.app:netbeans-launcher#1.2.2
me@linux:~> nuts netbeans-launcher
1.2.2
me@linux:~> nuts install net.thevpc.app:netbeans-launcher#1.2.1
me@linux:~> nuts netbeans-launcher
1.2.1
me@linux:~> nuts install net.thevpc.app:netbeans-launcher#1.2.2
1.2.2

Purpose

• A+B : read A main package and B dependencies
• A+B? : ask, if confirmed, read A main package and B dependencies.
• require : deploy package as 'required'
• install : deploy package as 'installed'
• nothing : do nothing

• require : install the package and all of its dependencies as required class installed package
• install : install the package and all of its dependencies as first class installed package
• reinstall : re-install or re-required the package and all of its dependencies
• repair : repair (re-install or re-required) the given dependency

nuts update 
    check if a newer version of nuts or any of the provided 
    is available in the current workspace and perform update by downloading (fetch)
    and installing the artifact. The updated version is promoted to 'default' version.

##)  
SYNOPSIS:



    nuts update [<-options>]...  ...  ...
        update the nuts to the latest version.
        If --force is armed, will re-download the artifacts and its dependencies.

    nuts update [ --to-version  ]
        update the current workspace to latest version or to the given version if provided.

##)  
OPTIONS:



    -a | --all
        force updates of both workspace's api, runtime extensions and installed artifacts

    -w | --ws | --workspace
        update all workspace's related artifacts (api, runtime and extensions)

    -i | --installed
        update all installed artifacts

    -e | --extensions
        update all workspace's extensions

    -c | --companions
        update all companions

    -r | --runtime
        update workspace's runtime artifact (minor workspace update)

    -A | --api
        update workspace's api (major workspace update)

    -v  or --to-version 
        force updates to the provided  (may be a downgrade)

     ...
        provide arguments to pass to updater



##)  
EXAMPLES



    nuts update --help
        show this help and exit

    nuts update
        update workspace

    nuts update netbeans-launcher
        update netbeans-launcher

• 'unavailable' if no registered repository can serve that artifact
• 'available' if there is at least one repository that can serve that artifact
• 'fetched' if there is a repository that can serve the artifact from local machine. This happens either if the repository is a local one (for instance a folder repository) or the repository has already downloaded and cached the artifact
• 'installed' if the artifact is fetched and installed in the the machine.
• 'installed default' if the artifact is installed and marked as default

# all artifacts that start with netbeans, whatever groupId they belong to
# nuts search netbeans*

# all artifacts that start with netbeans, whatever groupId they belong to. same as the latter.
# nuts search *:netbeans*

# all artifacts in the net.thevpc.app groupId
# nuts search net.thevpc.*:*

# all artifacts in the net.thevpc.* groupId which includes all of net.thevpc.app and net.thevpc.app.example for instance.
# nuts search net.thevpc.*:*

# all artifacts that start with netbeans and is available for windows operating system in x86_64 architecture
# nuts search netbeans*?os=windows&arch=x86_64

# all netbeans launcher version that are greater than 1.2.0 (excluding 1.2.0)
# nuts search netbeans-launcher#]1.2.0,[

# all netbeans launcher version that are greater than 1.2.0 (including 1.2.0)
# nuts search netbeans-launcher#[1.2.0,[

• --installed (or -i) : search only for installed artifacts

• --local : search only for fetched artifacts

• --remote : search only for non fetched artifacts

• --online : search in installed then in local then in remote, stop when you first find a result.

• --anywhere (or -a) : search in installed and local and remote, return all results.

me@linux:~> nuts search -i -l
I-X 2019-08-26 09:53:53.141 anonymous vpc-public-maven net.thevpc.app:netbeans-launcher#1.2.1
IcX 2019-08-24 11:05:49.591 admin     maven-local      net.thevpc.app.nuts.toolbox:nsh#0.8.5.0
I-x 2019-08-26 09:50:03.423 anonymous vpc-public-maven net.thevpc.app:kifkif#1.3.3

me@linux:~> nuts search -i -l --json

[
{
  "id": "vpc-public-maven://net.thevpc.app:netbeans-launcher#1.2.1",
  "descriptor": {
    "id": "net.thevpc.app:netbeans-launcher#1.2.1",
    "parents": [],
    "packaging": "jar",
    "executable": true,
    ...
  }
 }
]

Indeed, all of nuts commands support the following formats : plain, json, xml, table and tree because nuts adds support to multi format output by default. You can switch to any of them for any command by adding the right option in nuts (typically --plain, --json, --xml, --table and --tree). I know this is awesome!.

search is a very versatile command, you are welcome to run "nuts search --help" to get more information.

search for artifacts

##)  
SYNOPSIS:



    nuts search [<-options>]...  ...  ...
        search for 

##)  
OPTIONS:



    --lenient
        when an id is found but its descriptor and/or its file are not found, do not raise an error and continue. default no

    --all-versions
        return all versions of the same ids. if no will always return the latest one. default yes

    --duplicates
        return the same version from distinct repositories if found. default yes

    --distinct
        remove duplicates . default false

    -L | --latest | --latest-versions
        return latest version of each searched id. equivalent to --all-versions=no

    -S | --single | --single-versions
        return one instance of each version even if found in distinct repositories. equivalent to --duplicate=no

    -s | --sort
        sort result. default no

    --main
        include main result. This is meaningful when one needs to find only dependencies, and hence turns this flag to no. default yes

    --dependencies
        include dependencies in result. default no

    --main-only
        include main result and no dependencies. equivalent to --main=yes --dependencies=no

    --dependencies-only
        include dependencies and no main. equivalent to --main=no --dependencies=no

    --main-and-dependencies
        include main result and no dependencies. equivalent to --main=yes --dependencies=yes

    -r | --repository 
        include repository in the search process. if none defined, all repositories are searched.

    --arch x86|amd64|ia64|ppc|sparc
        include architecture in the search process. if none defined, all architectures are searched.

    --packaging jar|war|...
        include packaging in the search process. if none defined, all packagings are searched.

    --cached
        include cached in the search process. default yes

    --indexed
        include search index in the search process. default yes

    --effective
        compute effective descriptor. default no

    --content
        include content. default no

    --install-info
        include install information. default false

    --location
        force found contents to be copied to location

    -f | --fetch offline|online|anywhere|installed|remote
        include fetch mode in the search process. if none defined, all fetch modes are searched.

    --offline | -F 
        equivalent to --fetch=offline

    --online | -O
        equivalent to --fetch=online

    --anywhere | -a
        equivalent to --fetch=anywhere

    --installed | -i 
        search for installed only packages

    --included
        search for included packages in other installations

    --deployed
        search for installed and required (as dependencies) packages

    --remote | -R
        equivalent to --fetch=remote

    --optional
        relevant when --dependencies is armed.
        --optional=     : search for all dependencies, including optional (default)
        --optional=yes  : search for optional dependencies only
        --optional=no   : search for non optional dependencies only

    --scope api|implementation|compile|provided|import
               |runtime|system|test-compile|test-provided
               |test-runtime|test|run|run-test|other|all
        relevant when --dependencies is armed.
        include scope in the search dependencies process.
        if none defined, only run scope is searched.

    --default | --default-versions
        find only default installed versions. This is meaningful with --installed flag

    --libs | --lib
        find libraries (non app) only

    --apps | --app
        find applications (non libraries) only

    --nuts-apps |--nuts-app
        find nuts applications only

    --extensions | --extension
        find extensions only

    --runtime
        find nuts runtime only

    --companions | --companion
        find companions only

    --api-version
        find artifacts compatible with the given api-version

    -l
    --long
    --display-long
        equivalent to --display=long

    --display=
        define columns to display (ordered list of columns, comma separated)
        Accepted columns are:
            status             : show nuts status using condensed format using 3 characters
                char #1 : show installation status
                    I : means 'installed' and is 'default'
                    i : means 'installed' and is not default
                    d : means 'dependency' (aka 'required') locally deployed
                    f : means 'fetched' locally but not installed
                    r : means 'remote' (not fetched)
                char #2 : show package type
                    a : nuts 'api' package
                    r : nuts 'runtime' package
                    e : nuts 'extension' package
                    c : nuts 'companion' package
                    - : other package
                char #3 : show application status
                    X : means executable nuts application (implementing NutsApplication)
                    x : means executable regular application
                    - : means non executable or unknown
                char #4 : show scope status (when applicable)
                    c : compile/api scope
                    i : implementation scope
                    r : runtime scope
                    s : system scope
                    p : provided scope
                    t : test (any) scope
                    m : import scope
                    O : other
                    - : unknown
            install-date       : artifact install date
            install-user       : artifact install user
            id                 : artifact id
            name               : simple name
            packaging          : artifact packaging (jar, war, msi, exe, ...)
            arch               : artifact supported architectures (x86, x64,...)
            platform           : artifact supported platforms (java, dotnet, ...)
            os                 : artifact supported operation systems (Linux, Windows,...)
            osdist             : artifact supported OS distributions (OpenSuSE, Ubuntu, ...)
            de                 : artifact supported OS Desktop Environment (KDE, GNOME,...)
            exec-entry         : Main class
            file-name          : artifact file name
            file               : artifact file path
            var-location       : artifact var folder
            temp-location      : artifact temp folder
            config-location    : artifact config folder
            lib-location       : artifact lib folder
            log-location       : artifact log folder
            cache-location     : artifact cache folder
            programs-location  : artifact programs folder
            run-location       : artifact run folder
            long               : equivalent to status, install-date, install-user, id
            all                : equivalent to all of the above

    --omit-env
        when formatting id, omit env

    --omit-face
        when formatting id, omit face

    --omit-group
        when formatting id, omit group

    --omit-imported-group
        when formatting id, omit imported group

    --omit-repo
        when formatting id, omit repository

    --highlight-imported-group
        when formatting id, highlight imported group

    --highlight-optional
        when formatting id, highlight optional

    --highlight-scope
        when formatting id, highlight scope



##)  
EXAMPLES



    nuts search --help
        show this help and exit

    nuts search
        search installed nuts

    nuts search --offline netbeans-*
        search all artifacts that start with "netbeans-" in all local repositories

    nuts search --anywhere netbeans-*
        search all artifacts that start with "netbeans-" in all local and remote repositories

    nuts -Zy -w test search --repository spring 
        search using spring repository only

    -Zy search -l --json 
        search locally installed artifacts in json format

    _   __      __       
   / | / /_  __/ /______   Network Updatable Things Services
  /  |/ / / / / __/ ___/   The Open Source Package Manager for Java (TM)
 / /|  / /_/ / /_(__  )    and other Things ... by vpc
/_/ |_/\__,_/\__/____/     https://github.com/thevpc/nuts
    version 0.8.5.0


SYNOPSIS:
nuts [<options>]... <command> <args> ...

For Help, type nuts help

configure nuts

##)  
SYNOPSIS:



    settings  []...

###)  
alias:


    settings list aliases []
        ...

    settings add alias =...
        ...

    settings remove alias ...
        ...

###)  
alias:


    settings list imports []
        ...

    settings (import|ia) ...
        ...

    settings (unimport|ir) ...
        ...

###)  
archetype:


    settings (list archetypes|la)
        ...

###)  
backup/restore:


    settings backup (--file|-f)=
    settings backup 
        ...

    settings restore (--file|-f)=
    settings restore 
        ...

###)  
cli-id:


    settings cli-id
    settings get cli-id

    settings cli-id=
    settings set cli-id 
        ...

    settings restore (--file|-f)=
    settings restore 
        ...

###)  
connect:


    settings connect --password= @:port
        telnet a remote tcp server
        ...

###)  
delete:


    settings delete bin|conf|var|log|temp|cache|run ...
        delete workspace folder

###)  
update stats:


    settings update stats ...
        update repository stats

###)  
java:


    settings add java --search
        deploys an id from registered repository to another

    settings add java ...
        deploys an id from registered repository to another

    settings remove java ...
        deploys an id from registered repository to another

###)  
repository:


    settings list repos...
        ...
    settings add repo ...
        ...

    settings remove repo ...
        ...
    settings enable repo ...
        ...
    settings disable repo ...
        ...
    settings edit repo  ...
        ...

###)  
user:


    settings list users...
        ...
    settings add user ...
        ...

    settings remove user ...
        ...
    settings enable user ...
        ...
    settings disable user ...
        ...
    settings edit user  ...
        ...
    settings password...
        ...

###)  
log:


    settings (set log level|sll) verbose|finest|fine|finer|info|warning|severe|error|config|off|all
        ...

    settings (log level|get log level)
        ...

    settings install log
        ...

###)  
ndi (nuts desktop integration):


    settings ndi [...] ...
        ...
    OPTIONS:
    --fetch|-t...
        ...
    (--workdir|-d)=...
        ...
    --icon=...
        ...
    --menu=(supported|never|always|preferred)...
        ...
    --menu-category=...
        ...
    --menu-name=...
        ...
    --shortcut-name=...
        ...
    --shortcut-path=...
        ...
    --desktop=(supported|never|always|preferred)...
        ...
    --desktop-name=...
        ...
    --spawn|--external|-x...
        ...
    --embedded|-b...
        ...
    --terminal...
        ...
    --env|e...
        ...
    --system...
        ...
    --current-user...
        ...
    --as-root...
        ...
    --run-as=...
        ...
    (--exec-options|-X)=...
        ...
    (--installed|-i)...
        ...
    (--companions|-c)...
        ...
    (--switch)...
        ...
    (--ignore-unsupported-os)...
        ...
    (--workspace|-w)=...
        ...
    (--name|-n)=...
        ...


##)  
EXAMPLES:



    settings --file myjar.jar
        settings the myjar.jar file to default local repository

    deploy --id example:some-thing --to system
        settings the latest version of example:some-thing to system repository

    _   __      __       
   / | / /_  __/ /______   Network Updatable Things Services
  /  |/ / / / / __/ ___/   The Open Source Package Manager for Java (TM)
 / /|  / /_/ / /_(__  )    and other Things ... by vpc
/_/ |_/\__,_/\__/____/     https://github.com/thevpc/nuts
    version 0.8.5.0


SYNOPSIS:
nuts [<options>]... <command> <args> ...

For Help, type nuts help

push a nuts to remote repository

##)  
SYNOPSIS:



    push 
        pushes a nuts to remote server



##)  
EXAMPLES:



    push my-group:my-name
        pushes the nuts

    _   __      __       
   / | / /_  __/ /______   Network Updatable Things Services
  /  |/ / / / / __/ ___/   The Open Source Package Manager for Java (TM)
 / /|  / /_/ / /_(__  )    and other Things ... by vpc
/_/ |_/\__,_/\__/____/     https://github.com/thevpc/nuts
    version 0.8.5.0


SYNOPSIS:
nuts [<options>]... <command> <args> ...

For Help, type nuts help

configure nuts

##)  
SYNOPSIS:



    settings  []...

###)  
alias:


    settings list aliases []
        ...

    settings add alias =...
        ...

    settings remove alias ...
        ...

###)  
alias:


    settings list imports []
        ...

    settings (import|ia) ...
        ...

    settings (unimport|ir) ...
        ...

###)  
archetype:


    settings (list archetypes|la)
        ...

###)  
backup/restore:


    settings backup (--file|-f)=
    settings backup 
        ...

    settings restore (--file|-f)=
    settings restore 
        ...

###)  
cli-id:


    settings cli-id
    settings get cli-id

    settings cli-id=
    settings set cli-id 
        ...

    settings restore (--file|-f)=
    settings restore 
        ...

###)  
connect:


    settings connect --password= @:port
        telnet a remote tcp server
        ...

###)  
delete:


    settings delete bin|conf|var|log|temp|cache|run ...
        delete workspace folder

###)  
update stats:


    settings update stats ...
        update repository stats

###)  
java:


    settings add java --search
        deploys an id from registered repository to another

    settings add java ...
        deploys an id from registered repository to another

    settings remove java ...
        deploys an id from registered repository to another

###)  
repository:


    settings list repos...
        ...
    settings add repo ...
        ...

    settings remove repo ...
        ...
    settings enable repo ...
        ...
    settings disable repo ...
        ...
    settings edit repo  ...
        ...

###)  
user:


    settings list users...
        ...
    settings add user ...
        ...

    settings remove user ...
        ...
    settings enable user ...
        ...
    settings disable user ...
        ...
    settings edit user  ...
        ...
    settings password...
        ...

###)  
log:


    settings (set log level|sll) verbose|finest|fine|finer|info|warning|severe|error|config|off|all
        ...

    settings (log level|get log level)
        ...

    settings install log
        ...

###)  
ndi (nuts desktop integration):


    settings ndi [...] ...
        ...
    OPTIONS:
    --fetch|-t...
        ...
    (--workdir|-d)=...
        ...
    --icon=...
        ...
    --menu=(supported|never|always|preferred)...
        ...
    --menu-category=...
        ...
    --menu-name=...
        ...
    --shortcut-name=...
        ...
    --shortcut-path=...
        ...
    --desktop=(supported|never|always|preferred)...
        ...
    --desktop-name=...
        ...
    --spawn|--external|-x...
        ...
    --embedded|-b...
        ...
    --terminal...
        ...
    --env|e...
        ...
    --system...
        ...
    --current-user...
        ...
    --as-root...
        ...
    --run-as=...
        ...
    (--exec-options|-X)=...
        ...
    (--installed|-i)...
        ...
    (--companions|-c)...
        ...
    (--switch)...
        ...
    (--ignore-unsupported-os)...
        ...
    (--workspace|-w)=...
        ...
    (--name|-n)=...
        ...


##)  
EXAMPLES:



    settings --file myjar.jar
        settings the myjar.jar file to default local repository

    deploy --id example:some-thing --to system
        settings the latest version of example:some-thing to system repository

    _   __      __       
   / | / /_  __/ /______   Network Updatable Things Services
  /  |/ / / / / __/ ___/   The Open Source Package Manager for Java (TM)
 / /|  / /_/ / /_(__  )    and other Things ... by vpc
/_/ |_/\__,_/\__/____/     https://github.com/thevpc/nuts
    version 0.8.5.0


SYNOPSIS:
nuts [<options>]... <command> <args> ...

For Help, type nuts help

show minimal welcome message
    show minimal welcome message

##)  
SYNOPSIS:



    nuts welcome [<-options>]

show workspace information and exit
    show workspace detailed information (paths and libraries)

##)  
SYNOPSIS:



    nuts info [<-options>]

##)  
OPTIONS



    -r | --repos
        show repositories

    -c | --cmd
        show command arguments

    -e | --env
        show environment info (Java™ version, os version, ...)

    -p | --path
        show workspace locations

    -f | --fancy
        show paths variables in multi rows

    --add =
        add extra key=value to info list

    -g | --get  ...
        filter names to include only the given names



##)  
EXAMPLES



    nuts info --help
        show this help and exit

    nuts info --json
        show info in json format

info command is a more verbose command than version. It shows a lot of other nuts properties that describe the booted workspace, such as the workspace name, the store locations (artifacts, caches, ....)

me@linux:~> nuts info
name                     = default-workspace
nuts-api-version         = 0.8.5
nuts-api-id              = net.thevpc.app.nuts:nuts#0.8.5
nuts-runtime-id          = net.thevpc.app.nuts:nuts-core#0.8.5.0
nuts-runtime-path        = ~/.cache/nuts/default-workspace/boot/net/vpc/app/nuts/nuts-core/0.8.5.0/nuts-core-0.8.5.0.jar;~/.cache/nuts/default-workspace/boot/net/vpc/app/nuts/nuts/0.8.5/nuts-0.8.5.jar;~/.cache/nuts/default-workspace/boot/com/google/code/gson/gson/2.8.5/gson-2.8.5.jar;~/.cache/nuts/default-workspace/boot/org/fusesource/jansi/jansi/1.17.1/jansi-1.17.1.jar
nuts-workspace-id        = 99b73002-804d-4e4c-9a13-f57ac1f40b3d
nuts-store-layout        = linux
nuts-store-strategy      = exploded
nuts-repo-store-strategy = exploded
nuts-global              = false
nuts-workspace           = ~/.config/nuts/default-workspace
nuts-workspace-apps      = ~/.local/share/nuts/apps/default-workspace
nuts-workspace-config    = ~/.config/nuts/default-workspace/config
nuts-workspace-var       = ~/.local/share/nuts/var/default-workspace
nuts-workspace-log       = ~/.local/log/nuts/default-workspace
nuts-workspace-temp      = ~/nuts/default-workspace
nuts-workspace-cache     = ~/.cache/nuts/default-workspace
nuts-workspace-lib       = ~/.local/share/nuts/lib/default-workspace
nuts-workspace-run       = /run/user/1000/nuts/default-workspace
nuts-open-mode           = open-or-create
nuts-secure              = false
nuts-gui                 = false
nuts-inherited           = false
nuts-recover             = false
nuts-reset               = false
nuts-debug               = false
nuts-trace               = true
nuts-read-only           = false
nuts-install-companions  = false
nuts-skip-welcome        = false
java-version             = 1.8.0_222
platform                 = java#1.8.0_222
java-home                = /usr/lib64/jvm/java-1.8.0-openjdk-1.8.0/jre
java-executable          = /usr/lib64/jvm/java-1.8.0-openjdk-1.8.0/jre/bin/java
java-classpath           = ~/.m2/repository/net/vpc/app/nuts/nuts/0.8.5/nuts-0.8.5.jar
java-library-path        = /usr/java/packages/lib/amd64:/usr/lib64:/lib64:/lib:/usr/lib
os-name                  = linux#4.12.14-lp151.28.13-default
os-family                = linux
os-dist                  = opensuse-leap#15.1
os-arch                  = x86_64
user-name                = me
user-home                = /home/me
user-dir                 = /home/me
command-line-long        = --color=system --trace --open-or-create --exec info
command-line-short       = -t info
inherited                = false
inherited-nuts-boot-args = 
inherited-nuts-args      = 
creation-started         = 2019-08-26 00:02:10.903
creation-finished        = 2019-08-26 00:02:11.223
creation-within          = 320ms
repositories-count       = 5

me@linux:~> nuts version
0.8.5/0.8.5.0

Here the version command show api version (0.8.5) and the impl version (0.8.5.0)

show version
    show version

##)  
SYNOPSIS:



    nuts version [<-options>]
    nuts --version
    nuts -version
    nuts -v

##)  
OPTIONS:



    -a | --all
        include all versions (api, runtime, Java™ and operating system)

    --add = 
        include key=value pair in the result



##)  
EXAMPLES



    nuts version -a
        show all versions

    nuts -v
        show version

    nuts -Zy -w test version --table 
        show version in tabular format

me@linux:~> nuts help version
version :
nuts version
nuts --version
nuts -version
nuts -v
      show version and exit
...

will show help of the version command.

me@linux:~> nuts version --help

license command shows license of nuts and exits. nuts adopts GNU General Public License v3 which is quite permissive.

me@linux:~> nuts license
    _   __      __       
   / | / /_  __/ /______   Network Updatable Things Services
  /  |/ / / / / __/ ___/   The Open Source Package Manager for Java (TM)
 / /|  / /_/ / /_(__  )    and other Things ... by vpc
/_/ |_/\__,_/\__/____/     https://github.com/thevpc/nuts
    version 0.8.5.0



 Is a new Open Source Package Manager to help install packages
 and libraries for runtime execution. Nuts is the ultimate companion for
 maven (and other build managers) as it helps installing all package
 dependencies at runtime. Nuts is not tied to java and is a good choice
 to share shell scripts and other 'Things' . It is based on an extensible
 architecture to help supporting a large range of sub managers / repositories.
 
 Copyright (C) 2016-2019 Taha BEN SALAH
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 3 of the License, or
 (at your option) any later version.

show license info and exit

##)  
SYNOPSIS:



    nuts license



##)  
EXAMPLES



    nuts license --helpsh
        show this help and exit

    nuts license
        show license and exit