# Command Line Interface¶

Conjure supports a number of commands. A command is provided as the first argument to Conjure on the command line. It is followed by a number of mandatory arguments (if any) depending on the command, and a number of optional arguments.

Some command line arguments to Conjure are positional, for example the command name. Another example of positional arguments is the path to a file required by the conjure pretty command. This argument can just be provided after the command name, like: conjure pretty myfile.essence.

Non-positional arguments are provided using options. Some options require an additional value to be provided. Other options are flags and do not expect additional values. For example the conjure pretty command takes a flag called --remove-unused, which removes unused decision variables from the model before pretty printing it. This option is a flag that takes no values. However, the conjure modelling command takes an option called --output-directory, which specifies the directory under which Conjure places its output files. This option requires a value.

Options can have short or long names. Following the common convention, short option names are preceded by a single dash and long options names are preceded by two dashes. For example --output-directory is a long name for an option, and -o is a short name for the same option.

The general form of a Conjure run is as follows: conjure [COMMAND] ... [OPTIONS].

Following is the list of primary commands provided by Conjure. They can be used to generate Essence’ models from Essence files, translate parameter files and solution files for a specific Essence’ model, and more.

modelling
The main act. Given a problem specification in Essence, produce constraint programming models in Essence’.
translate-parameter
Refinement of parameter files written in Essence for a particular Essence’ model. The Essence’ model needs to be generated by Conjure.
translate-solution
Translation of solutions back to Essence.
validate-solution
Validating a solution.
solve
This is a combined mode, and it is available for convenience. It runs conjure in the modelling mode followed by parameter refinement if required, then Savile Row + Minion to solve, and then solution translation.

If no primary command is provided, modelling is assumed.

Conjure also supports a few additional commands on top of the primary commands listed above. These commands are not required for the normal operation of the tool. They are implemented to aid development and testing.

pretty
Pretty print as Essence file to stdout. This mode can be used to view a binary Essence file in textual form.
diff
Diff on two Essence files. Works on models, parameters, and solutions.
type-check
Type-checking a single Essence file.
split
Split an Essence files to various smaller files. Useful for testing.
symmetry-detection
Dump some JSON to be used as input to ferret for symmetry detection.
parameter-generator
Generate an Essence model describing the instances of the problem class defined in the input Essence model. An error will be printed if the model has infinitely many instances.

Commands typically take additional arguments. Each command provides a separate help message. To see the command specific help message, run: conjure COMMAND --help.

## Help output¶

The following is Conjure’s full help message for each command, provided for reference. These messages may change between releases of Conjure.

 Conjure: The Automated Constraint Modelling Tool conjure [COMMAND] ... [OPTIONS] The command line interface of Conjure takes a command name as the first argument followed by more arguments depending on the command.This help text gives a list of the available commands.For details of a command, pass the --help flag after the command name.For example: 'conjure translate-solution --help' Common flags: --help Display help message --version Print version information conjure [modelling] [OPTIONS] ESSENCE_FILE The main act. Given a problem specification in Essence, produce constraint programming models in Essence'. Logging & Output: -o --output-directory=DIR Where to save generated models.Default value: 'conjure-output' --numbering-start=INT Starting value for output files.Default value: 1 --smart-filenames Use "smart names" for models.Directs Conjure to use the answers when producing a filename and to ignore the order of questions. Only useful if 'f' is used for questions. --log-level=LOGLEVEL Log level. --verbose-trail Generate verbose trails. --rewrites-trail Generate trails about the applied rewritings. --log-rule-fails Generate logs for rule failures. (Caution: can be a lot!) --log-rule-successes Generate logs for rule applications. --log-rule-attempts Generate logs for rule attempts. (Caution: can be a lot!) --log-choices Store the choices in a way that can be reused by -al --output-format=FORMAT Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions minizinc: minizinc format for data files, only used for solutions --line-width=INT Line width for pretty printing.Default: 120 Model generation: --responses=ITEM A comma separated list of integers.If provided, these will be used as the answers during interactive model generation instead of prompting the user. --responses-representation=ITEM A comma separated list of variable name : integer pairs.If provided, these will be used as the answers during interactive model generation instead of prompting the user for the variable representation questions.See --dump-representations for a list of available representation options. --estimate-number-of-models Calculate (a lower bound on) the number of models, instead of running the usual modelling mode. --portfolio=PORTFOLIO Portfolio size. When it is set to N, Conjure will try to generate up to N models. -q --strategy-q=STRATEGY Strategy for selecting the next question to answer. Options: f (for first), i (for interactive), r (for random), x (for all). Prepend a (for auto) to automatically skip when there is only one option at any point.Default value: f -a --strategy-a=STRATEGY Strategy for selecting an answer. Same options as strategy-q. c picks the most 'compact' option at every decision point. s picks the 'sparsest' option at every decision point: useful for --representations-givensDefault value: ai --representations=STRATEGY Strategy for choosing a representation.Default value: same as --strategy-a --representations-finds=STRATEGY Strategy for choosing a representation for a decision variable.Default value: same as --representations --representations-givens=STRATEGY Strategy for choosing a representation for a parameter.Default value: s (for sparse) --representations-auxiliaries=STRATEGY Strategy for choosing a representation for an auxiliary variable.Default value: same as --representations --representations-quantifieds=STRATEGY Strategy for choosing a representation for a quantified variable.Default value: same as --representations --representations-cuts=STRATEGY Strategy for choosing a representation for cuts in 'branching on'.Default value: same as --representations --channelling Whether to produce channelled models (true by default). --representation-levels Whether to use built-in precedence levels when choosing representations. Used to cut down the number of generated models.Default: true --follow-model=ITEM Provide a Conjure-generated Essence Prime model to be used as a guide during model generation. Conjure will try to imitate the modelling decisions from this file. --seed=INT Random number generator seed. --limit-models=INT Maximum number of models to generate. --choices=FILE Choices to use for -al, either an eprime file (created by --log-choices), or a json file. General: --limit-time=INT Limit in seconds of real time. conjure translate-parameter [OPTIONS] Refinement of Essence parameter files for a particular Essence' model.The model needs to be generated by Conjure. Flags: --eprime=ESSENCE_FILE An Essence' model generated by Conjure. --essence-param=FILE An Essence parameter for the original problem specification. --eprime-param=FILE An Essence' parameter matching the Essence' model.Default is 'foo.eprime-param' if the Essence parameter file is named 'foo.param'. Logging & Output: --log-level=LOGLEVEL Log level. --output-format=FORMAT Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions minizinc: minizinc format for data files, only used for solutions --line-width=INT Line width for pretty printing.Default: 120 General: --limit-time=INT Limit in seconds of real time. conjure translate-solution [OPTIONS] Translation of solutions back to Essence. Flags: --eprime=FILE An Essence' model generated by Conjure.Mandatory. --essence-param=FILE An Essence parameter for the original problem specification.Mandatory. --eprime-solution=FILE An Essence' solution for the corresponding Essence' model. --essence-solution=FILE An Essence solution for the original problem specification.By default, its value is the value of --eprime-solution with extensions replaced by '.solution'. Logging & Output: --log-level=LOGLEVEL Log level. --output-format=FORMAT Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions minizinc: minizinc format for data files, only used for solutions --line-width=INT Line width for pretty printing.Default: 120 General: --limit-time=INT Limit in seconds of real time. conjure validate-solution [OPTIONS] Validating a solution. Flags: --essence=ESSENCE_FILE Problem specification in Essence. --param=FILE Essence parameter file. --solution=FILE Essence solution. Logging & Output: --log-level=LOGLEVEL Log level. --output-format=FORMAT Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions minizinc: minizinc format for data files, only used for solutions --line-width=INT Line width for pretty printing.Default: 120 General: --limit-time=INT Limit in seconds of real time. conjure solve [OPTIONS] ESSENCE_FILE [PARAMETER_FILE(s)] A combined mode for convenience.Runs Conjure in modelling mode followed by parameter translation if required, then Savile Row + Minion to solve, and then solution translation. General: --validate-solutions Enable solution validation. --limit-time=INT Limit in seconds of real time. --graph-solver Create input files for the Glasgow graph solver. --cgroups Setup and use cgroups when solving with Savile Row. --number-of-solutions=ITEM Number of solutions to find; "all" enumerates all solutions.Default: 1 --copy-solutions Whether to place a copy of solution(s) next to the Essence file or not.Default: on Logging & Output: -o --output-directory=DIR Where to save generated models.Default value: 'conjure-output' --numbering-start=INT Starting value for output files.Default value: 1 --smart-filenames Use "smart names" for models.Directs Conjure to use the answers when producing a filename and to ignore the order of questions. Only useful if 'f' is used for questions. --solutions-in-one-file Place all solutions in a single file instead of generating a separate file per solution.Off by default. --log-level=LOGLEVEL Log level. --verbose-trail Generate verbose trails. --rewrites-trail Generate trails about the applied rewritings. --log-rule-fails Generate logs for rule failures. (Caution: can be a lot!) --log-rule-successes Generate logs for rule applications. --log-rule-attempts Generate logs for rule attempts. (Caution: can be a lot!) --log-choices Store the choices in a way that can be reused by -al --output-format=FORMAT Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions minizinc: minizinc format for data files, only used for solutions --line-width=INT Line width for pretty printing.Default: 120 Model generation: --responses=ITEM A comma separated list of integers.If provided, these will be used as the answers during interactive model generation instead of prompting the user. --responses-representation=ITEM A comma separated list of variable name : integer pairs.If provided, these will be used as the answers during interactive model generation instead of prompting the user for the variable representation questions.See --dump-representations for a list of available representation options. --portfolio=PORTFOLIO Portfolio size. When it is set to N, Conjure will try to generate up to N models. -q --strategy-q=STRATEGY Strategy for selecting the next question to answer. Options: f (for first), i (for interactive), r (for random), x (for all). Prepend a (for auto) to automatically skip when there is only one option at any point.Default value: f -a --strategy-a=STRATEGY Strategy for selecting an answer. Same options as strategy-q. c picks the most 'compact' option at every decision point. s picks the 'sparsest' option at every decision point: useful for --representations-givensDefault value: c --representations=STRATEGY Strategy for choosing a representation.Default value: same as --strategy-a --representations-finds=STRATEGY Strategy for choosing a representation for a decision variable.Default value: same as --representations --representations-givens=STRATEGY Strategy for choosing a representation for a parameter.Default value: s (for sparse) --representations-auxiliaries=STRATEGY Strategy for choosing a representation for an auxiliary variable.Default value: same as --representations --representations-quantifieds=STRATEGY Strategy for choosing a representation for a quantified variable.Default value: same as --representations --representations-cuts=STRATEGY Strategy for choosing a representation for cuts in 'branching on'.Default value: same as --representations --channelling Whether to produce channelled models (true by default). --representation-levels Whether to use built-in precedence levels when choosing representations. Used to cut down the number of generated models.Default: true --follow-model=ITEM Provide a Conjure-generated Essence Prime model to be used as a guide during model generation. Conjure will try to imitate the modelling decisions from this file. --seed=INT Random number generator seed. --limit-models=INT Maximum number of models to generate. --use-existing-models=FILE File names of Essence' models generated beforehand.If given, Conjure skips the modelling phase and uses the existing models for solving.The models should be inside the output directory (See -o). Options for other tools: --savilerow-options=ITEM Options passed to Savile Row. --solver-options=ITEM Options passed to the backend solver. --solver=ITEM Backend solver. Possible values: - minion (CP solver) - gecode (CP solver) - chuffed (CP solver) - glucose (SAT solver) - glucose-syrup (SAT solver) - lingeling/plingeling/treengeling (SAT solver) - cadical (SAT solver) - kissat (SAT solver) - minisat (SAT solver) - bc_minisat_all (AllSAT solver, only works with --number-of-solutions=all) - nbc_minisat_all (AllSAT solver, only works with --number-of-solutions=all) - open-wbo (MaxSAT solver, only works with optimisation problems) - coin-or (MIP solver, implemented via MiniZinc) - cplex (MIP solver, implemented via MiniZinc) - boolector (SMT solver, supported logics: bv) - yices (SMT solver, supported logics: bv, lia, idl) - z3 (SMT solver, supported logics: bv, lia, nia, idl)Default: minionDefault logic for SMT solvers is bitvector (bv).Append a dash and the name of a logic to the solver name to choose a different logic. For example yices-idl. conjure ide [OPTIONS] ESSENCE_FILE IDE support features for Conjure.Not intended for direct use. Logging & Output: --log-level=LOGLEVEL Log level. --line-width=INT Line width for pretty printing.Default: 120 General: --limit-time=INT Limit in seconds of real time. IDE Features: --dump-declarations Print information about top level declarations. --dump-representations List the available representations for decision variables and parameters. conjure pretty [OPTIONS] ESSENCE_FILE Pretty print as Essence file to stdout.This mode can be used to view a binary Essence file in textual form. Flags: --normalise-quantified Normalise the names of quantified variables. --remove-unused Remove unused declarations. Logging & Output: --log-level=LOGLEVEL Log level. --output-format=FORMAT Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions minizinc: minizinc format for data files, only used for solutions --line-width=INT Line width for pretty printing.Default: 120 General: --limit-time=INT Limit in seconds of real time. conjure diff [OPTIONS] FILE FILE Diff on two Essence files. Works on models, parameters, and solutions. Logging & Output: --log-level=LOGLEVEL Log level. --output-format=FORMAT Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions minizinc: minizinc format for data files, only used for solutions --line-width=INT Line width for pretty printing.Default: 120 General: --limit-time=INT Limit in seconds of real time. conjure type-check [OPTIONS] ESSENCE_FILE Type-checking a single Essence file. Logging & Output: --log-level=LOGLEVEL Log level. General: --limit-time=INT Limit in seconds of real time. conjure split [OPTIONS] ESSENCE_FILE Split an Essence file to various smaller files. Useful for testing. Logging & Output: -o --output-directory=DIR Where to save generated models.Default value: 'conjure-output' --log-level=LOGLEVEL Log level. --output-format=FORMAT Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions minizinc: minizinc format for data files, only used for solutions --line-width=INT Line width for pretty printing.Default: 120 General: --limit-time=INT Limit in seconds of real time. conjure symmetry-detection [OPTIONS] ESSENCE_FILE Dump some JSON to be used as input to ferret for symmetry detection. Logging & Output: --json=JSON_FILE Output JSON file.Default is 'foo.essence-json'if the Essence file is named 'foo.essence' --log-level=LOGLEVEL Log level. --output-format=FORMAT Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions minizinc: minizinc format for data files, only used for solutions --line-width=INT Line width for pretty printing.Default: 120 General: --limit-time=INT Limit in seconds of real time. conjure parameter-generator [OPTIONS] ESSENCE_FILE Generate an Essence model describing the instances of the problem class defined in the input Essence model.An error will be printed if the model has infinitely many instances. Integer bounds: --MININT=INT The minimum integer value for the parameter values.Default: 0 --MAXINT=INT The maximum integer value for the parameter values.Default: 100 Logging & Output: --log-level=LOGLEVEL Log level. --output-format=FORMAT Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions minizinc: minizinc format for data files, only used for solutions --line-width=INT Line width for pretty printing.Default: 120 General: --limit-time=INT Limit in seconds of real time. conjure autoig [OPTIONS] ESSENCE_FILE OUTPUT_FILE Generate an Essence model describing the instances of the problem class defined in the input Essence model.An error will be printed if the model has infinitely many instances. Flags: --generator-to-irace Convert the givens in a hand written generator model to irace syntax. --remove-aux Remove lettings whose name start with Aux Logging & Output: --log-level=LOGLEVEL Log level. --output-format=FORMAT Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions minizinc: minizinc format for data files, only used for solutions --line-width=INT Line width for pretty printing.Default: 120 General: --limit-time=INT Limit in seconds of real time. conjure boost [OPTIONS] ESSENCE_FILE Strengthen an Essence model as described in "Reformulating Essence Specifications for Robustness",which aims to make search faster. Logging & Output: --log-level=LOGLEVEL Log level. --log-rule-successes Generate logs for rule applications. --output-format=FORMAT Format to use for output. All output formats can also be used for input. plain: default binary: a binary encoding astjson: a JSON dump of the internal data structures, quite verbose json: a simplified JSON format, only used for parameters and solutions minizinc: minizinc format for data files, only used for solutions --line-width=INT Line width to use during pretty printing.Default: 120 General: --limit-time=INT Time limit in seconds (real time). conjure tsdef [OPTIONS] Generate data type definitions in TypeScript.These can be used when interfacing with Conjure via JSON. Logging & Output: --log-level=LOGLEVEL Log level. General: --limit-time=INT Limit in seconds of real time.