ksconf package

Create a Splunk app or add on tarball (.spl) file from an app directory.

ksconf package can do useful things like, exclude unwanted files, combine layers, set the application version and build number, drop or promote the local directory into default.

Note that some arguments, like the FILE support special values that can be automatically evaluated at runtime. For example the placeholders {{version}} or {{git_tag}} can be expanded into the output tarball filename.

If both layering and templating are in use at the same time, be aware that templates are rendered prior to layering operations. This allows, for example, one layer to include a simple indexes.conf file and another layer to include an indexes.conf.j2 template.

usage: ksconf package [-h] [-f SPL] [--app-name APP_NAME]
                      [--blocklist BLOCKLIST] [--allowlist ALLOWLIST]
                      [--layer-method {dir.d,disable}] [-I PATTERN]
                      [-E PATTERN] [--enable-handler {jinja}]
                      [--template-vars TEMPLATE_VARS] [--follow-symlink]
                      [--set-version VERSION] [--set-build BUILD]
                      [--allow-local | --block-local | --merge-local]
                      [--release-file RELEASE_FILE]

Positional Arguments


Source directory for the Splunk app.

Named Arguments

-f, --file

Name of splunk app file (tarball) to create. Placeholder variables in {{var}} syntax can be used here.


Specify the top-level app folder name. If this is not given, the app folder name is automatically extracted from the basename of SOURCE. Placeholder variables, such as {{app_id}} can be used here.

--blocklist, -b

Pattern for files/directories to exclude. Can be given multiple times. You can load multiple exclusions from disk by using file://path which can be used with .gitignore for example. (Default includes: .git*, *.py[co], __pycache__, .DS_Store)

--allowlist, -a

Remove a pattern that was previously added to the blocklist.


Possible choices: jinja

Enable optional file handling support


Set template variables as key=value or YAML/JSON, if filename prepend with @

--follow-symlink, -l

Follow symbolic links pointing to directories. Symlinks to files are always followed.


Set application version. By default the application version is read from default/app.conf. Placeholder variables such as {{git_tag}} can be used here.


Set application build number.


Allow the local folder to be kept as-is WARNING: This goes against Splunk packaging practices, and will cause AppInspect to fail. However, this option can be useful for private package transfers between servers, app backups, or other admin-like tasks.


Block the local folder and local.meta from the package.


Merge any files in local into the default folder during packaging. This is the default behavior.

Layer filtering

If the app being packaged includes multiple layers, these arguments can be used to control which ones should be included in the final app file. If no layer options are specified, then all layers will be included.


Possible choices: dir.d, disable

Set the layer type used by SOURCE. Additional description provided in in the combine command.

-I, --include

Name or pattern of layers to include.

-E, --exclude

Name or pattern of layers to exclude from the target.

Advanced Build Options

The following options are for more advanced app building workflows.


Write the path of the newly generated archive file (SPL) after the archive is written. This is useful in build scripts when the SPL contains variables so the final name may not be known ahead of time.


The following variables are currently available for use during package building. These are referenced using the {{var}} syntax. See the implementation in AppVarMagic if you’d like to contribute additional variables.

Supported Variables






Get id from [package] in app.conf. This must be the app folder name for any app published to Splunkbase.



Get build from [install] in app.conf



Get version from [launcher] in app.conf



Run git describe --tags --always --dirty. Common prefixes are removed such as v or release- from the tag name.



Run git log -n1 --pretty=format:%h -- .



Run git rev-parse --short HEAD



List of unique ksconf layers used to build the app. Layers are separated by an double underscores (__). If no layers were used then an empty string is returned.



Unique hash of unique ksconf layers used. This is a truncated SHA256 of the layers_list variable.


ksconf package -f my_app.tgz MyApp

A more realistic example where the version number in app.conf is managed by some external process, possibly a tool like bumpversion.

bumpversion minor
ksconf package MyApp \
    --set-version={{git_tag}} \
    -f dist/my_app-{{version}}.tgz \
echo "Build complete, upload $(<.artifact) to SplunkBase"

This will output a message like: Build complete, upload dist/my_app-1.3.0.tgz to SplunkBase

And of course this workflow could be further automated using Splunkbase API calls.

See also

More sophisticated builds can be achieved using the BuildManager