# The debusine command

The `debusine` command is a command line interface to the Debusine API. It is provided by the `debusine-client` package and contains many sub-commands.

The configuration file is documented in The debusine client configuration file.

## Output of the `debusine` command

If the `debusine` command succeeds, it prints relevant information to the standard output in YAML format.

If an error occurs, the error messages will be printed to the standard error.

## Return values

Return values of the `debusine` command:

Return value | Meaning
--- | ---
0 | Success
1 | Error: unhandled exception. Please report the error
2 | Error: wrong arguments and options
3 | Error: any other type of error such as connection to the server is not possible, invalid configuration file, etc.

## Sub-commands

`debusine` provides sub-commands to manipulate Work requests, Workflows, Artifacts, etc., described in `--help`:

    $ debusine --help
    usage: debusine [-h] [--server SERVER] [--config-file CONFIG_FILE] [-s] [-d]
                    {list-work-requests,show-work-request,create-work-request,manage-work-request,create-workflow-template,[...]}
                    ...

    Interacts with a Debusine server.

    positional arguments:
      {list-work-requests,show-work-request,create-work-request,manage-work-request,create-workflow-template,[...]}
                            Sub command
        list-work-requests  List all work requests
        show-work-request   Print the status of a work request
        create-work-request
                            Create a work request and schedule the execution. Work request is read from stdin in YAML format
        manage-work-request
                            Manage a work request
        create-workflow-template
                            Create a workflow template
    [...]

If you have multiple servers configured, then you may need to select which one to use. You can do this using `--server FQDN/SCOPE` (for example, `--server debusine.debian.net/debian`), or using `--server NAME` (where the available names are shown by `debusine setup`).

For convenience in scripts, you can use the `DEBUSINE_SERVER_NAME` environment variable instead of specifying `--server`. When both are used, `--server` has priority.

Each sub-command is self-documented, use `debusine sub-command --help`:

    $ debusine create-workflow --help
    usage: debusine create-workflow [-h] [--workspace WORKSPACE] [--data DATA] template_name

    positional arguments:
    [...]