Skip to end of metadata
Go to start of metadata

Command Line Utilities

Ewimpex is a command line utility that allows you to list, backup and restore any or all knowledgebases from the database. It is not necessary for the  Agiloft application server, such as JBoss, to be running when you execute this command, so you can turn off access to the system during exports and imports.


ewimpex <kblist | backup | restore | help> [options] 

The available commands: kblist, backup, restore, and help are described below with examples.


The kblist command outputs a list of all available knowledge bases in the database, one knowledge base per line. Each line contains a tab-separated (\t) knowledge base ID and name, for example: 

1 Demo
    2 My test kb
    3 Working kb


The backup command exports selected knowledgebases to a specified folder or a new backup, and requires one of more of the following options: 

 k (-kbases) - list of comma-separated knowledge bases
    names to backup.
    For example: -k Demo,Tickets,Support or --kbases Demo,Tickets,Support
a (-all) - ignores -k option and tells ewimpex to backup all
    user knowledge bases, including admin one.
    For example: -a or --all
o (-output) - folder to save knowledge bases to.
    If not set, ewimpex will create a "backup" folder inside the current
    working directory and place the backups in it.
    -b - backup damaged knowledge bases as well.
    Will backup kbases that are flagged as damaged
    (ie with a projecttype > 1), this flag is OFF by

The knowledgebases save to the folder you specify, using the original file names and the extension. All non-standard characters in file names are automatically replaced by the underscore character.


The restore command restores one or many knowledgebases that were previously backed up using the ewimpex utility or the  Agiloft GUI.
Restore requires one or more of the following options: 

f (-file ) - knowledge base file name to restore.
    For example -f or --file "My Best"
a (-all ) - tells to restore all knowledge bases, found in the
    specified folder.
    Option -f will be ignored, if present.
s (-skip-admin) - skips admin KB from restore list
    This option is only applicable with the -a option and is useful
    to avoid importing the admin KB
r (-replace) - instructs ewimpex to overwrite system tables during
    See the documentation for more details.
    -x - disables knowledge bases patching.
    This option is useful when importing a knowledge base without having
    the application server (eg JBoss) running. If this is used,
    the imported knowledge bases will be patched when the application
    next starts up.

If you are restoring a KB that already exists, ewimpex will add a prefix to the restored knowledgebase in order to avoid naming conflicts. For example, if you have a Demo knowledgebase installed and are restoring another Demo knowledgebase from the file, the restored knowledgebase is named 0_Demo. After restoration, you can log in to  Agiloft as an administrator and rename or delete unneeded copies of the databases.

Common Options

In addition to the command-specific options listed above, there are several options that specify the database parameters and are common to all commands. If none of these options are set, ewimpex finds and uses the  Agiloft installation data. Therefore, the following parameters are optional. 

 w (-ew-home ) - path to the installation
    folder to use
    installation data. (if auto-detection fails for some reason)
d (-database-type ) - type of the database. Currently, mysql, db2 and
    mssql are supported.
h (-database-address ) - IP address of the database server to connect
    with; is used by default
P (-database-port ) - port number for the database.
    Database-specific default port value is used if this option is missed
    -H - combines options -h and -P and allows setting the database
    address and port as one option.
    For example: -H localhost:3306
u (-database-username ) - username to use for database login
p (-database-password ) - password to use for database login
n (-database-name ) - database name to connect to.
    sw2_std is used by default
v (-verbose) - turn on debug output.
    Print a lot of debugging information to the console.
    Use only to investigate problems or to generate a bug report for

Error codes:

On success, ewimpex returns a zero value. On error, the system provides an error message and returns negative error code. For example:

     -1 - database connection problems
     -2 - invalid parameters set
     -3 - invalid database structure 
     -4 - internal error during import/export
     -5 - specified knowledge base file is invalid or damaged
     -6 - specified knowledge base is not an admin knowledge base
     -7 ... -999 - unexpected error

Use Cases and Examples

Get a list of all installed knowledgebases:

  • On Windows from INSTALL_DIR\bin\ run: 
    • ewimpex kblist 
  • On Linix/Unix from INSTALL_DIR/bin/ run:
    • ./ewimpex kblist

Export all knowledgebases into the folder

  • On Windows from INSTALL_DIR\bin\ run:
    • ewimpex backup --all --output C:\backups 
  • On Linux/Unix from INSTALL_DIR/bin/ do:
    • ./ewimpex backup --all --output ~/backups

Export one knowledgebase

  • On Windows from INSTALL_DIR\bin\ run:
    • ewimpex backup --kbases Demo --output C:\demos 
  • On Linux/Unix from INSTALL_DIR/bin/ run:
    • ./ewimpex backup --kbases Demo --output ~/demos

Export list of knowledgebases

  • On Windows from INSTALL_DIR\bin\ run:
    • ewimpex backup --kbases Demo,MyCRM --output C:\MyKB 
  • On Linux/Unix from INSTALL_DIR/bin/ run:
    • ./ewimpex backup --kbases Demo,MyCRM --output ~/MyKB

Import all knowledgebases from a folder to  Agiloft system

Existing knowledgebases will not be overwritten.

  • On Windows from INSTALL_DIR\bin\ run:
    • ewimpex restore --all C:\backups 
  • On Linux/Unix from INSTALL_DIR/bin/ run:
    • ./ewimpex restore --all ~/backups

Import one knowledgebase

  • On Windows from INSTALL_DIR\bin\ run:
    • ewimpex restore --file c:\ 
  • On Linux/Unix from INSTALL_DIR/bin/ run:
    • ./ewimpex restore --file ~/MyKB/