Hudson CLI

Hudson
Home
Downloads
Mailing lists and IRC
Source code
Reporting Bugs
Documents
Meet Hudson
Use Hudson
Extend Hudson
Plugins
SCMs
Triggers
Build Tools
Build Wrappers
Notifiers
Reporters
Slave Launchers and Controllers
Uploaders
Other Post-build Actions
Ext. Site Integration
UI Plugins
Page Decorators
Authentication and User Management
Cluster Management and Distributed Build
CLI Extensions
Maven
Misc
Others
Container-specific Notes
Site Map

Starting 1.302, Hudson has a built-in CLI client that allows you to access Hudson from a script or from your shell. This is convenient for automation of routine tasks, bulk updates, trouble diagnosis, and so on.

Obtaining CLI

Hudson CLI is distributed inside hudson.war. Download it from http://yourserver.com/jnlpJars/hudson-cli.jar. In theory, the CLI jar is dependent on the version of Hudson, but in practice, we expect to be able to retain compatibility between different versions of Hudson.

Running CLI

The general syntax is as follows (the design is similar to tools like svn/git):

java -jar hudson-cli.jar [-s HUDSON_URL] command [options...] [arguments...]

HUDSON_URL can be specified via the environment variable $HUDSON_URL. The 'help' command will give you the list of the available commands, which depends on the server you are talking to.

Extending CLI

Plugins installed on Hudson server can add custom CLI commands to Hudson. See Writing CLI commands for more details.

Working with Credentials

If your Hudson requires authentication, use --username and --password or --password-file options to specify the credentials. To avoid doing this for every command, you can also use the login CLI command once (with the same credentials parameters), and after that you may use other commands without specifying credentials.
Note that not every authentication type supports these parameters for credentials. Prior to Hudson 1.373, only authentication in Hudson's own database was supported. As of 1.373, LDAP is also supported. If the CLI reports these are invalid parameters, file an issue for your authentication type and ask them to extend AbstractPasswordBasedSecurityRealm instead of directly from SecurityRealm to get support for these parameters.

Change History: Note that a security hole in CLI commands was fixed in Hudson 1.371, and that CLI login did not work properly for many commands until 1.375.

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

Comments (16)

 

  1. May 05, 2009

    Rémy EVEN says:

    What about protocol and port using by hudson-cli ? Thanks

    What about protocol and port using by hudson-cli ?

    Thanks

  2. May 19, 2009

    Frederic Jean says:

    Is it possible to pass credentials to hudson-cli?

    Is it possible to pass credentials to hudson-cli?

  3. Feb 04, 2010

    benson margulies says:

    Can I pass parameters to the 'build' command?

    Can I pass parameters to the 'build' command?

  4. Apr 09, 2010

    Axel Heider says:

    Is there a list of commands that can be used? I did not find anything, so if the...

    Is there a list of commands that can be used? I did not find anything, so if there is something a link in the Wiki page would help.

    1. May 03, 2010

      Jes struck says:

      use help as a command the it's self documented

      use help as a command the it's self documented

  5. May 24, 2010

    Thomas Matthijs says:

    The correct HUDSON_URL is your-url + "/cli", if you go that address the example ...

    The correct HUDSON_URL is your-url + "/cli", if you go that address the example there will even lie to you (not including /cli)

    1. Sep 25, 2010

      Alexander Lehmann says:

       @Thomas: actually HUDSON_URL is http://server:8080/hudson/ (or whatever) a...

       @Thomas: actually HUDSON_URL is http://server:8080/hudson/ (or whatever) and that can be passed to the command, since it adds /cli at the end.

      (at least in 1.377 it does)

  6. Sep 25, 2010

    Alexander Lehmann says:

    I'd like to propose an edit to the section about Credentials: The parameters &#...

    I'd like to propose an edit to the section about Credentials:

    The parameters --username and --password can appear only after the command and not before.

    (I found that somewhat confusing since the login applies to the service and not to the individual command)

  7. Dec 13, 2010

    Dave Bottger says:

    FYI - The option to wait when using the "build" command is "-s" i.e. java -...

    FYI - The option to wait when using the "build" command is "-s"

    i.e. java -jar hudson-cli.jar -s http://<server>/hudson/ build --username <username> --password-file </path/to/file/containing/plain/text/password> -s -p buildparam1=<value1> -p buildparam2=<value2>

                                                                                                                                                                                                                    ^^ ---- that is the "-s" that tells the build to wait

  8. Jan 09, 2011

    Adam Zehavi says:

    Hi, I was wondering... I've jumped into Hudson, and I saw a piece of CLI like th...

    Hi, I was wondering... I've jumped into Hudson, and I saw a piece of CLI like this:

    java -jar hudson-cli.jar -s http://<server>/hudson/ build -s <Job Name> -p buildparam1=<value1> -p buildparam2=<value2> GROUP=<blah>

    and then I got that the buildparam1 and buildparam2 are the ones defined within the job, yet I need to set their value?!
    I've been told by the guys I'm working with/for that the number of parameters supplied in the cli must match exactly to the parameters defined in the web UI job editing page. Which brings me to these questions:

    Does the number of parameters matters? what if I supply an extra unused parameter? what if supply less? would it get the default value as I defined in the editor?

    Thanks in advance,
    Adam Zehavi.

  9. Apr 01, 2011

    Niels Ull Harremoes says:

    When running groovysh from the windows command line, I get strange escape chars:...

    When running groovysh from the windows command line, I get strange escape chars:

    java -jar jenkins-cli.jar -s http://myserver:8080 groovysh
    ?[32mGroovy Shell?[0m (1.6.0, JVM: 1.6.0_23)
    Type '?[1mhelp?[0m' or '?[1m\h?[0m' for help.
    -------------------------------------------------------------------------------
    ?[1mgroovy:?[0m000?[1m>?[0m
    ?[1mgroovy:?[0m000?[1m>?[0m ?[1mgroovy:?[0m000?[1m>?[0m

    (the ?'s above are actually small left arrows)

    What am I missing?

  10. Jul 20, 2011

    ken yu says:

    many thanks that the CLI is very useful in my project, it will be perfect if a m...

    many thanks that the CLI is very useful in my project, it will be perfect if a more detail guide or sample provided, such as when creates a new job it will read stdin as a configuration XML file, the question is how to define the XML file, what infomation is mandatory and what format we have to follow.

    1. Aug 28, 2011

      Tony Dahbura says:

      Ken: Look in your .hudson directory under jobs.  You should see directorie...

      Ken:

      Look in your .hudson directory under jobs.  You should see directories named the names of your jobs and inside them are a config.xml file which you can use for a model.

  11. Aug 28, 2011

    Tony Dahbura says:

    Hi all-we have been using hudson for a bit and wanted to use the CLI to create ...

    Hi all-we have been using hudson for a bit and wanted to use the CLI to create new projects...

    The problem we are having is how to get the svn credentials put in automatically when creating a new job via the CLI. 

    I noticed there is a subversion.credentials xml file created when we enter these via the web gui. 

    Not sure how to get the command line config.xml file we upload to also create this file or create this file in some other way? 

    Any help would be greatly appreciated!

    Thanks.

  12. Oct 06, 2011

    Indra Gunawan says:

    Our hudson URL is on https.  May I know the argument to bypass Certificate ...

    Our hudson URL is on https.  May I know the argument to bypass Certificate Check to use the CLI?

    I am getting this error:

    bash-3.00$ java -jar hudson-cli.jar -s https://sjc-hudson22-lnx:9081/ help
    Exception in thread "main" java.io.IOException: Failed to connect to https://sjc-hudson22-lnx:9081/
            at hudson.cli.CLI.getCliTcpPort(CLI.java:116)
            at hudson.cli.CLI.<init>(CLI.java:72)
            at hudson.cli.CLI.<init>(CLI.java:62)
            at hudson.cli.CLI.main(CLI.java:175)
    Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
            at com.sun.net.ssl.internal.ssl.Alerts.getSSLException(Alerts.java:174)
            at com.sun.net.ssl.internal.ssl.SSLSocketImpl.fatal(SSLSocketImpl.java:1611)
            at com.sun.net.ssl.internal.ssl.Handshaker.fatalSE(Handshaker.java:187)
            at com.sun.net.ssl.internal.ssl.Handshaker.fatalSE(Handshaker.java:181)
            at com.sun.net.ssl.internal.ssl.ClientHandshaker.serverCertificate(ClientHandshaker.java:1035)
            at com.sun.net.ssl.internal.ssl.ClientHandshaker.processMessage(ClientHandshaker.java:124)
            at com.sun.net.ssl.internal.ssl.Handshaker.processLoop(Handshaker.java:516)
            at com.sun.net.ssl.internal.ssl.Handshaker.process_record(Handshaker.java:454)
            at com.sun.net.ssl.internal.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:884)
            at com.sun.net.ssl.internal.ssl.SSLSocketImpl.performInitialHandshake(SSLSocketImpl.java:1112)
            at com.sun.net.ssl.internal.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1139)
            at com.sun.net.ssl.internal.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1123)
            at sun.net.www.protocol.https.HttpsClient.afterConnect(HttpsClient.java:418)
            at sun.net.www.protocol.https.AbstractDelegateHttpsURLConnection.connect(AbstractDelegateHttpsURLConnection.java:166)
            at sun.net.www.protocol.https.HttpsURLConnectionImpl.connect(HttpsURLConnectionImpl.java:133)
            at hudson.cli.CLI.getCliTcpPort(CLI.java:114)
            ... 3 more
    Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
            at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:285)
            at sun.security.validator.PKIXValidator.engineValidate(PKIXValidator.java:191)
            at sun.security.validator.Validator.validate(Validator.java:218)
            at com.sun.net.ssl.internal.ssl.X509TrustManagerImpl.validate(X509TrustManagerImpl.java:126)
            at com.sun.net.ssl.internal.ssl.X509TrustManagerImpl.checkServerTrusted(X509TrustManagerImpl.java:209)
            at com.sun.net.ssl.internal.ssl.X509TrustManagerImpl.checkServerTrusted(X509TrustManagerImpl.java:249)
            at com.sun.net.ssl.internal.ssl.ClientHandshaker.serverCertificate(ClientHandshaker.java:1014)
            ... 14 more
    Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
            at sun.security.provider.certpath.SunCertPathBuilder.engineBuild(SunCertPathBuilder.java:174)
            at java.security.cert.CertPathBuilder.build(CertPathBuilder.java:238)
            at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:280)
            ... 20 more

    Thank you.

    -Indra

  13. Dec 05, 2011

    Tony Dahbura says:

    Does anyone know how to setup the SVN credentials when entering a new job into H...

    Does anyone know how to setup the SVN credentials when entering a new job into Hudson via the CLI? 

    Would like to add a new job, but the SVN URL and credentials and other information is preventing the CI from doing this correctly?