Confluence Command Line Interface

Name	Confluence CLI
Vendor	Bob Swift and other contributors
Authors	Bob Swift
Homepage	http://confluence.atlassian.com/display/CONFEXT/Confluence+Command+Line+Interface
Issue Management	http://developer.atlassian.com/jira/browse/CSOAP
Continuous Integration	n/a
Categories	Remote Access
Most Recent Version	1.3.0
Availability	Confluence v2.5.2 to v2.10-m5
State	Stable
Support
License	Freeware / Open Source (BSD)
Price	Free
Release Docs	http://confluence.atlassian.com/display/CONFEXT/Confluence+Command+Line+Interface
Java API Docs	n/a
Download Source	http://svn.atlassian.com/svn/public/contrib/confluence/confluence-cli/trunk/
Download JAR	confluence-cli-1.3.0-distribution.zip

Additional support information

JVM requirements for client	1.x.x - Java 1.5 and above 0.7.0 - Java 1.4 and above

Command line interface client for Confluence

This is a command line interface (CLI) for remotely accessing Confluence using SOAP APIs. This provides a convenient way to automate Confluence administration and include Confluence 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. It uses Confluence's SOAP remote API. It also serves as an example for writing a Java SOAP client for Confluence. Confluence SOAP Client in Java provides some historical information.

Additional information

Confluence CLI - creating pages from templates — Using the CLI to create a standard set of pages
Confluence CLI - Remote API support matrix — List remote API functions supported by the Confluence CLI

Installation

Unzip the distribution package and put the enclosed directory in a convenient location
Ensure Remote API is enabled in your Confluence installation
- You need to be a Confluence 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 confluence
On Linux (or Windows)
- Run java -jar release/confluence-cli-1.2.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 confluence.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.

Downloads for version 1.0 and up

Date	2008-May	2008-Jun	2008-Jul	2008-Aug	2008-Sep	2008-Oct	2008-Nov
Hits	24	59	70	52	78	85	56

Compatibility

CLI	2.5	Tested release	Download
1.3.0	¹	2.5.2, 2.7.1, 2.8	zip
1.2.0	¹	2.5.2, 2.7.1, 2.8	zip
1.1.0	¹	2.5.2, 2.7.1, 2.8-m9-r3	zip
1.0.0	¹	2.5.2, 2.7.1, 2.8-m7-r2	zip
0.7.0		2.5.2, 2.7.1	zip
0.6.0		2.2.9	zip
0.5.0		2.2.9
0.4.0		2.2.9
0.3.0			zip

Footnotes

1 - Some permissions functions do not work correctly on 2.5

Examples

This information is also available in the examples directory in the distribution.
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 confluence.bat file has been customized for your environment as noted above.

confluence --action addPage --title temp1 --space Test --content "This is page content \\ another line of content"

confluence --action storePage --title temp --space Test --content "This is page content \\ another line of content"

confluence --action removePage --title temp --space Test

confluence --action removePage --descendents --title html-simple --space Test

confluence --action storePage --title temp --space Test --content "This is page content \\ another line of content" --labels "testLabel1, testLabel2"

confluence --action renderPage --title temp1 --space Test --file confluence-cli\examples\output.txt

confluence --action getPageSource --title temp --space Test --file confluence-cli\examples\source.txt

confluence --action getPageList --space Test --file confluence-cli\examples\output.txt

confluence --action getPageList --title h3 --space Test --ancestors --file confluence-cli\examples\output.txt

confluence --action getPageList --title h1 --space Test --descendents --file confluence-cli\examples\output.txt

confluence --action getPageList --title h1 --space Test --children --file confluence-cli\examples\output.txt

confluence --action addComment --title temp --space Test --comment "this is a comment\\another line"

confluence --action addLabels --title temp --space Test --labels "testLabel"

confluence --action removeLabels --title temp --space Test --labels "testLabel1, testLabel2, notFound"

confluence --action addLabels --space Test --labels "spaceLabel1, spaceLabel2, spaceLabel3"

confluence --action removeLabels --space Test --labels "spaceLabel1, spaceLabel-notFound, spaceLabel2"

confluence --action addAttachment --title temp --space Test --name input.txt --content "This is page content \\ another line of content"

confluence --action getAttachment --title temp --space Test --name input.txt --file confluence-cli\examples\output.txt

confluence --action removeAttachment --title temp --space Test --name input.txt

confluence --action renamePage --title temp --space Test --newTitle temp2 --parent h1

confluence --action storeNews --title temp --space Test --content "This is page content \\ another line of content"

confluence --action storeNews --title temp --space Test --content "This is page has been updated \\ another line of content" --dayOfMonth 1

confluence --action storeNews --title temp --space Test --file confluence-cli\examples\input.txt --labels "testLabel1, testLabel2"

confluence --action getNewsSource --title temp --space Test --file confluence-cli\examples\source.txt --dayOfMonth 1

confluence --action renderNews --title temp --space Test --file confluence-cli\examples\output.txt --news

confluence --action addLabels --title temp --space Test --labels "testLabel" --dayOfMonth 1

confluence --action getLabelList --space Test --title temp --file confluence-cli\examples\output.txt --news

confluence --action getLabelList --space Test --file confluence-cli\examples\output.txt --labels "testLabel"

confluence --action getLabelList --recentlyUsed

confluence --action getLabelList --recentlyUsed --space Test

confluence --action getLabelList --mostPopular

confluence --action getLabelList --mostPopular --space Test

confluence --action getNewsList --space Test --file confluence-cli\examples\output.txt

confluence --action removeLabels --title temp --space Test --labels "testLabel1, testLabel2" --dayOfMonth 1

confluence --action removeNews --title temp --space Test

confluence --action removeNews --title temp --space Test --dayOfMonth 1

confluence --action getPermissionList --space Test --userId user2t --file confluence-cli\examples\output.txt

confluence --action getPermissionList --space Test --title h1 --file confluence-cli\examples\output.txt

confluence --action addPermissions --space Test --userId user2t --permissions "VIEWSPACE, EDITSPACE, COMMENT, SETSPACEPERMISSIONS, SETPAGEPERMISSIONS, EXPORTSPACE, EXPORTPAGE, CREATEATTACHMENT, EDITBLOG,REMOVEPAGE, REMOVECOMMENT, REMOVEBLOG, REMOVEATTACHMENT, REMOVEMAIL"

confluence --action removePermissions --space Test --userId user2t --permissions "REMOVEPAGE, REMOVECOMMENT, REMOVEBLOG, REMOVEATTACHMENT, REMOVEMAIL, SETSPACEPERMISSIONS"

confluence --action addPermissions --space Test --userId user1t --title temp1 --permissions "view, edit"

confluence --action removePermissions --space Test --userId user2t --title temp1 --permissions "EDIT"

confluence --action copyPermissions --space Test --title temp1 --newSpace Test --newTitle h3

confluence --action addPermissions --space Test --userId user1t --title h1 --permissions "EDIT" --descendents

confluence --action getPermissionList --space Test --title h1 --file confluence-cli\examples\output.txt

confluence --action addUser --userId user

confluence --action addGroup --group group

confluence --action addUserToGroup --userId user --group group

confluence --action addUserWithFile --file confluence-cli\examples\addUserWithFile.csv

confluence --action addUserToGroupWithFile --file confluence-cli\examples\addUserToGroupWithFile.csv

confluence --action getUserList

confluence --action getGroupList

confluence --action getGroupList --userId user2t

confluence --action removeUserFromGroupWithFile --file confluence-cli\examples\addUserToGroupWithFile.csv

confluence --action removeUserFromGroup --userId user --group group

confluence --action removeUserWithFile --file confluence-cli\examples\addUserWithFile.csv

confluence --action removeUser --userId user

confluence --action removeGroup --group group

confluence --action getSpace --space Test

confluence --action getSpaceList --file confluence-cli\examples\output.txt

confluence --action exportSpace --space Test --file confluence-cli\examples\output.zip

confluence --action exportSpace --space Test --file confluence-cli\examples\output.pdf --exportType PDF

confluence --action exportSpace --space Test --file confluence-cli\examples\output.html --exportType HTML

confluence --action removeSpace --space Test

confluence --action addSpace --space Test

confluence --action loadFiles --space Test --file confluence-cli\examples\html-simple --parent home --group confluence-administrators

confluence --action login > login

confluence --action logout

Using a login token

For repeated actions, the login can be done once and re-used. Write the login token to a file by redirecting stdout to a file and then re-used by using the -l flag to read it back from stdin. The token is valid for a limited time (Atlassian default of 30 minutes) and is invalid after the logout action is taken.

confluence --action login > login
confluence --action getSpaceList -l < login
confluence --action logout -l < login

Help text

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:
  confluence [--help] (-a|--action) <action> [--debug] [-v|--verbose]
  (-s|--server) <server> (-u|--user) <user> (-p|--password) <password> [--login
  <login>] [--service <service>] [-l|--loginFromStandardInput] [(-t|--title)
  <title>] [(-f|--file) <file>] [(-c|--content) <content>] [--comment <comment>]
  [--parent <parent>] [--name <name>] [--labels <labels>] [--newTitle <newTitle>]
  [--space <space>] [--newSpace <newSpace>] [--userId <userId>] [--userFullName
  <userFullName>] [--userEmail <userEmail>] [--userPassword <userPassword>]
  [--group <group>] [--defaultGroup <defaultGroup>] [--permissions <permissions>]
  [--dayOfMonth <dayOfMonth>] [--count <count>] [--exportType <exportType>]
  [--mime <mime>] [--findReplace <findReplace>] [--news] [--exportAttachments]
  [--mostPopular] [--recentlyUsed] [--ancestors] [--descendents] [--children]
  [--replace]


	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.
        addPage - Add a new page.
        	 Required parameters: space, title, content, file
        	 Optional parameters: parent, labels, replace, findReplace
        storePage - Create or update a page.
        	 Required parameters: space, title, content, file
        	 Optional parameters: parent, labels, findReplace
        removePage - Remove a page and, optionally, all descendents.
        	 Required parameters: space, title
        	 Optional parameters: descendents
        copyPage - Create or update a page from a source page.
        	 Required parameters: space, title, newSpace or newTitle
        	 Optional parameters: parent, labels, replace, findReplace
        renamePage - Rename or move a page.
        	 Required parameters: space, title, newTitle
        	 Optional parameters: parent
        getSource - Get page or news wiki text. Put to a file if specified.
        	 Required parameters: space, title
        	 Optional parameters: file, news, dayOfMonth
        render - Render page or news.
        	 Required parameters: space, title
        	 Optional parameters: file, news, dayOfMonth
        addAttachment - Add an attachment.
        	 Required parameters: space, title, file or content and name
        	 Optional parameters: mime, comment
        getAttachment - Get an attachment and put to a file.
        	 Required parameters: space, title, name, file
        removeAttachment - Remove an attachment.
        	 Required parameters: space, title, name
        addComment - Add a comment to a page or news.
        	 Required parameters: space, title, comment or content or file
        addLabels - Add labels to a page, news or space.
        	 Required parameters: space, labels
        	 Optional parameters: title, news, dayOfMonth
        removeLabels - Remove labels to a page, news or space.
        	 Required parameters: space, labels
        	 Optional parameters: title, news, dayOfMonth
        addNews - Add a news (blog) entry.
        	 Required parameters: space, title, file or content
        	 Optional parameters: dayOfMonth, labels, replace
        storeNews - Add or update a news (blog) entry.
        	 Required parameters: space, title, file or content
        	 Optional parameters: dayOfMonth, labels, replace
        removeNews - Remove a news (blog) entry.
        	 Required parameters: space, title
        	 Optional parameters: dayOfMonth
        getNewsSource - Get wiki text for a news (blog) entry. Put to a file if
        specified.
        	 Required parameters: space, title
        	 Optional parameters: dayOfMonth, file
        renderNews - Render a news (blog) entry. Put to a file if specified.
        	 Required parameters: space, title
        	 Optional parameters: dayOfMonth, file
        addUser - Add a new user.
        	 Required parameters: userId
        	 Optional parameters: userFullName, userEmail, userPassword
        addUserWithFile - Add users from comma separated file.
        	 Required parameters: file
        removeUser - Add a new user.
        	 Required parameters: userId
        removeUserWithFile - Remove users from comma separate file.
        	 Required parameters: file
        addGroup - Add a new group.
        	 Required parameters: group
        removeGroup - Remove a group.
        	 Required parameters: group
        addUserToGroup - Add user to a group.
        	 Required parameters: userId, group
        addUserToGroupWithFile - Add users to groups from comma separated file.
        	 Required parameters: file
        removeUserFromGroup - Remove user from a group.
        	 Required parameters: userId, group
        removeUserFromGroupWithFile - Remove users from groups from comma
        separated file.
        	 Required parameters: file
        addPermissions - Add permissions to page or space.
        	 Required parameters: space, permissions, userId or group
        	 Optional parameters: title, descendents
        removePermissions - Remove permissions from page or space.
        	 Required parameters: space, permissions, userId or group
        	 Optional parameters: title, descendents
        copyPermissions - Copy page permissions from a page to another page.
        	 Required parameters: space, title
        	 Optional parameters: newSpace, newTitle
        removeAllPermissionsForGroup - Remove all permissions for a group.
        	 Required parameters: group
        addSpace - Add a new space.
        	 Required parameters: space or userId
        removeSpace - Remove a space.
        	 Required parameters: space or userId
        getSpace - Get space information.
        	 Required parameters: space
        getSpaceList - Get list of spaces. Put to a file if specified.
        	 Required parameters: space
        	 Optional parameters: file
        getPageList - Get list of pages. Put to a file if specified.
        	 Required parameters: space
        	 Optional parameters: title, ancestors, descendents, children, file
        getNewsList - Get list of news items. Put to a file if specified.
        	 Required parameters: space
        	 Optional parameters: ancestors, descendents, children, file
        getLabelList - Get list of labels. Put to a file if specified.
        	 Optional parameters: space, title, news, mostPopular, recentlyUpdated,
        file
        getPermissionList - Get list of user or page permissions. Put to a file
        if specified.
        	 Required parameters: space
        	 Optional parameters: title, userId, file
        getUserList - Get list of users. Put to a file if specified.
        	 Optional parameters: file
        getGroupList - Get list of groups. Put to a file if specified.
        	 Required parameters: userId
        	 Optional parameters: file
        exportSpace - Export a space to a file
        	 Required parameters: space, exportType, file
        exportSite - Export site backup to a file
        	 Required parameters: file
        loadFiles - BETA. Load directory and files into a page hierarchy. HTM,
        HTML, and text files converted to pages. All other files added as
        attachments.
        	 Required parameters: space, file
        	 Optional parameters: title, content, parent, userid, group, replace

  [--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-axis/confluenceservice-v1)

  [-l|--loginFromStandardInput]
        Get login token from standard input.

  [(-t|--title) <title>]
        Page or news title.

  [(-f|--file) <file>]
        Path to file based content for attachments, pages, etc...

  [(-c|--content) <content>]
        Content for page, attachment or comment. (default: )

  [--comment <comment>]
        Comment text for comment or attachment comment. (default: )

  [--parent <parent>]
        Parent page name.

  [--name <name>]
        File name for attachment.

  [--labels <labels>]
        Comma separated list of labels.

  [--newTitle <newTitle>]
        New title of renamed page.

  [--space <space>]
        Space key.

  [--newSpace <newSpace>]
        New space key.

  [--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

  [--group <group>]
        Group for user management actions

  [--defaultGroup <defaultGroup>]
        Default group to move users on removeGroup action.

  [--permissions <permissions>]
        Comma separated list of permissions.
        	Page permissions:
        		view, edit
        	Space permissions:
        		viewsspace, editspace, comment, editblog, createattachment, 
        		removepage, removecomment, removeblog, removeattachment, removemail, 
        		setpagepermissions, setspacepermissions, 
        		exportpage, exportSpace

  [--dayOfMonth <dayOfMonth>]
        Day of month for news entry. Use negative values for going back to
        previous months. (default: 0)

  [--count <count>]
        Maximum count of entries to return. (default: 2147483647)

  [--exportType <exportType>]
        Export type (XML, HTML, PDF) for space export. (default: XML)

  [--mime <mime>]
        Attachment mime type if you want to override determination by file
        extension.

  [--findReplace <findReplace>]
        Find and replace text.

  [--news]
        Parameters represent a news item.

  [--exportAttachments]
        Export attachments for site export.

  [--mostPopular]
        Request most popular labels.

  [--recentlyUsed]
        Request recently used labels.

  [--ancestors]
        Ancestors for a page.

  [--descendents]
        All descendents for a page.

  [--children]
        Immediate children for a page.

  [--replace]
        Replace existing entity.

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

Release History

Version

Date

State

License

Price

1.3.0 (#13)

20 May 2008

Stable

Freeware / Open Source (BSD)

Free

Release Notes

Jira Issues

Key

Priority

Summary

Updated

asignee

Reporter

Status

CSOAP-26

Add ability to copy descendents or children on copyPage

May 20, 2008

Bob Swift

Closed

CSOAP-25

Refactor to use new common CLI code

May 20, 2008

Bob Swift

Closed

CSOAP-23

Add capability to replace text on storePage and copyPage

May 20, 2008

Bob Swift

Closed

CSOAP-22

Personal space support in addSpace and removeSpace actions is not documented

May 20, 2008

Bob Swift

Closed

CSOAP-20

Handle login timeout on loading users and groups from a file

May 20, 2008

Bob Swift

Closed

Contributors

Bob Swift — Developer

1.2.0 (#12)

16 Apr 2008

Stable

Freeware / Open Source (BSD)

Free

Release Notes

Jira Issues

Key

Priority

Summary

Updated

asignee

Reporter

Status

CSOAP-19

Add descendents support for remove page, add/remove page permissions

Apr 16, 2008

Bob Swift

Closed

CSOAP-17

copyPage action not working

Apr 16, 2008

Bob Swift

Closed

CSOAP-16

Load files support - experimental

Apr 16, 2008

Bob Swift

Closed

Contributors

Bob Swift — Developer

1.1.0 (#11)

07 Apr 2008

Stable

Freeware / Open Source (BSD)

Free

Release Notes

Jira Issues

Key

Priority

Summary

Updated

asignee

Reporter

Status

CSOAP-15

Refactoring

Apr 08, 2008

Bob Swift

Closed

CSOAP-14

Add support for page and space permissions

Apr 08, 2008

Bob Swift

Closed

CSOAP-13

Expand API coverage

Apr 08, 2008

Bob Swift

Closed

CSOAP-8

To enable addLabels feature for news

Apr 08, 2008

Sim Hua Soon

Resolved

Contributors

Bob Swift — Developer

1.0.0 (#10)

24 Mar 2008

Stable

Freeware / Open Source (BSD)

Free

Release Notes

Jira Issues

Key

Priority

Summary

Updated

asignee

Reporter

Status

CSOAP-12

Restructure to use Confluence SOAP client library

Mar 27, 2008

Bob Swift

Closed

CSOAP-11

Exception while getting page list for a space

Mar 27, 2008

Richard Michalsky

Closed

CSOAP-7

Add attachments options for exportSite

Mar 27, 2008

Bob Swift

Closed

CSOAP-5

Move source into SVN

Sep 16, 2007

Bob Swift

Closed

Contributors

Bob Swift — Developer

Older history

Date	Release	Notes
Apr 15, 2007	0.7	Get space and space list CSOAP-6
Mar 31, 2007	0.6	Label support CSOAP-3 Attachment mime type correction CSOAP-4
Feb 12, 2007	0.5	Get page source CSOAP-1 Get page list CSOAP-2
Dec 2, 2006	0.4	Added add/remove space Updated WSDL to Confluence 2.2.9 Eclipse definitions
July 17, 2006	0.3	Added renamePage function
May 13, 2006	0.2	Added user management functions Added Windows bat file
Feb 27, 2006	0.1	Initial release

Confluence Command Line Interface

Additional support information

Command line interface client for Confluence

Additional information

Installation

Usage

Downloads for version 1.0 and up

Compatibility

Examples

Using a login token

Help text

Error handling

License

Release History

Older history

Open Issues