This is a command line interface (CLI) for remotely accessing JIRA. This provides a convenient way to automate JIRA administration and include JIRA content as part of other automation. Examples are build and test automation or other business processes. This is a working command line client that can be used directly with your installation. This CLI uses JIRA's SOAP remote API.
Need to automate some JIRA capability?
The initial release includes basic automation capability. Additional capability will be added in the near future. Please create an issue to help prioritize content for the next release. If the capability you are seeking is not currently supported by JIRA remote API, you will need to open an enhancement request with JIRA.
Additional information
Download statistics
Date
2008-Jun
2008-Jul
2008-Aug
2008-Sep
2008-Oct
2008-Nov
Hits
21
14
23
21
20
24
Compatibility
CLI
3.11
3.12
Tested release
Notes
1.0.0
3.12.3
Likely works on previous releases
Related CLI clients
All CLI clients have standard interfaces and implementation.
Unzip the distribution package and put the enclosed directory in a convenient location
Ensure Remote API is enabled in your JIRA installation
You need to be an administrator
Go to General Administration under Remote API
Setting should be YES
Usage
On a command line, cd to the directory where you installed the client
On Windows
Run jira
On Linux (or Windows)
Run java -jar release/jira-cli-1.0.0.jar
This will show help text for the command line interface client
The client defaults to use a user of automation. Either add this user with all the authorities required to do the actions you want or specify a different user parameter
It is recommended that you open the jira.bat file with an editor and customize it for your environment by adding server, user, and password parameters. Follow the example in the comments and make sure you do not remove the %* at the end of the line.
Examples
Note: the information in this section is automatically generated, so if you have edit suggestions, add a comment. Otherwise, your edits will likely be replaced on the next update.
Note: the following examples assume that the jira.bat file has been customized for your environment as noted above.
This is the help text displayed by the default command or using --help. This gives the precise definition of parameters, however, it might be easier to just look at the examples. Note, the information in this section is automatically generated, so if you have edit suggestions, add a comment. Otherwise, your edits will be replaced on the next update.
Tips
Use single dash for single letter parameters - example: -v
Use double dash for multi-letter parameter - example: --help
When parameters are specified, most need a value - example: --action addPage
Some parameters are flags (boolean) and must not be followed by a value - example: --verbose
Parameter names are case sensitive, but, action values are not - example: --userid is invalid but --action addpage is equivalent to --action addPage
Some parameters become required once a specific action is chosen. This is indicated in the help text for each value.
Some parameters have both short (one letter) and long (more than one letter) parameter names - example: -a or --action are the same
Some parameters have default values, if so, they are indicated below - example: (default: automation)
Some parameters are required - indicated by (...) - example: (-a|--action) <action>
Some parameters are optional - indicated by [...] - example: [(-f|--file) <file>]
Values that have more than one word must be enclosed by double quotes - example: --title "this is my title"
Usage:
jira [--help] (-a|--action) <action> [--debug] [-v|--verbose] (-s|--server)
<server> (-u|--user) <user> (-p|--password) <password> [--login <login>]
[--service <service>] [-l|--loginFromStandardInput] [--group <group>] [--project
<project>] [--name <name>] [--description <description>] [--summary <summary>]
[--url <url>] [--lead <lead>] [--after <after>] [--date <date>] [--type <type>]
[--userId <userId>] [--userFullName <userFullName>] [--userEmail <userEmail>]
[--userPassword <userPassword>] [--permissionScheme <permissionScheme>]
[--notificationScheme <notificationScheme>] [--issueSecurityScheme
<issueSecurityScheme>]
Provides capability to make requests to a remote server.
Required parameters: action, server, password.
Optional parameters: user (likely required for your installation).
Other required and optional parameters depending on action requested.
[--help]
Prints this help message.
(-a|--action) <action>
Requested operation to perform. Valid actions (not case sensitive) are:
login - Login to remote server. Returns login token.
Required parameters: password
Optional parameters: user
logout - Logout of remote server.
createProject - Create a new project.
Required parameters: project, lead
Optional parameters: name, permissionScheme, notificationScheme,
issueSecurityScheme
deleteProject - Delete a project.
Required parameters: project
addVersion - Add a new version to a project.
Required parameters: project, name
Optional parameters: date
createIssue - Create a new issue for a project.
Required parameters: project, type, summary
Optional parameters: priority, reporter, assignee, date, description,
environment
listUsers - List users in a group.
Required parameters: group
[--debug]
Requests debug output, example: stack traces.
[-v|--verbose]
Requests verbose output.
(-s|--server) <server>
Server URL.
(-u|--user) <user>
User name for remote login. (default: automation)
(-p|--password) <password>
User password for remote login.
[--login <login>]
Login token from previous login request.
[--service <service>]
Service address extension. (default: /rpc/soap/jirasoapservice-v2)
[-l|--loginFromStandardInput]
Get login token from standard input.
[--group <group>]
Group name for user management actions
[--project <project>]
Project key
[--name <name>]
Name
[--description <description>]
Description
[--summary <summary>]
Summary of issue
[--url <url>]
URL
[--lead <lead>]
Project lead user id
[--after <after>]
Version name to add a version after
[--date <date>]
Date for version
[--type <type>]
Issue type
[--userId <userId>]
User id for user management and other actions
[--userFullName <userFullName>]
User name for user management actions
[--userEmail <userEmail>]
User email for user management actions
[--userPassword <userPassword>]
User password for user management actions
[--permissionScheme <permissionScheme>]
Permission scheme (default: Default Permission Scheme)
[--notificationScheme <notificationScheme>]
Notification scheme (default: Default Notification Scheme)
[--issueSecurityScheme <issueSecurityScheme>]
Issue security scheme (default: Default Issue Security Scheme)
Error handling
Care is taken to return the appropriate exit codes to the command processor. This makes it possible do error handling in automation scripts. Error and error logging output is directed to standard error.
Error type
Exit code
Description
SUCCESS
0
Normal exit
CLIENT_EXCEPTION
-1
The client has found a problem with the request and is reporting an error with a message.
PARAMETER_PROBLEM
-2
The client processed the command parameters and found a syntax error or missing required parameters according to the parameter definition
REMOTE_EXCEPTION
-3
The remote system has reported an error. The error message comes from the server.
FAILURE
-99
The client program failed in an unexpected way.;
License
The software provided for this tool has a BSD style license
The distribution ships binaries with various licenses (BSD, LGPL, and Apache)
Look in the license directory for detailed license information
In our Jira installation ver. 3.12.3 some issues in order to be created we must...
In our Jira installation ver. 3.12.3 some issues in order to be created we must some Jira default fields like component/s or some custom fields, how can we provide values in these fields via the command line to create an issue?
Some error examples:Remote error: com.atlassian.jira.rpc.exception.RemoteValidationException:
Unknown macro: {components=Component/s is required.}
Unknown macro: {customfield_10233=HR Bonus Type is required., components=Component/s is required., customfield_10234=HR Amount is required., customfield_10192=Period End is required., customfield_10191=Period Start is required.}
: []Thanks in advance.
Reply
The remote API is limited with respect to custom fields and you are probably getting the error because one of your custom fields is REQUIRED before an issue can be created. If you can remove the requirement by providing a default value. There are a number of enhancement requests on the JIRA remote API, I suggest you vote for the ones you are interested in. The CLI will be enhanced over time to include more capabilities, but all require the JIRA remote API to support the function first.
1.0.0
(#1)
Comments (1)
May 29, 2008
Kostas Balafas says:
In our Jira installation ver. 3.12.3 some issues in order to be created we must...In our Jira installation ver. 3.12.3 some issues in order to be created we must some Jira default fields like component/s or some custom fields, how can we provide values in these fields via the command line to create an issue?
Some error examples:Remote error: com.atlassian.jira.rpc.exception.RemoteValidationException:
: []
Remote error: com.atlassian.jira.rpc.exception.RemoteValidationException:
: []Thanks in advance.
Reply
The remote API is limited with respect to custom fields and you are probably getting the error because one of your custom fields is REQUIRED before an issue can be created. If you can remove the requirement by providing a default value. There are a number of enhancement requests on the JIRA remote API, I suggest you vote for the ones you are interested in. The CLI will be enhanced over time to include more capabilities, but all require the JIRA remote API to support the function first.
----------------------------------------------------
Thanks for the reply Bob