diff --git a/src/.merlin b/src/.merlin
index 320547d8e..3f3b9f6fe 100644
--- a/src/.merlin
+++ b/src/.merlin
@@ -1,5 +1,7 @@
 REC
 PKG cmdliner
 PKG curl
+PKG parsexp
+PKG uuidm
 B ../_build/src
 B ../_build/lib/bap_byteweight
diff --git a/src/bap_cmdline_terms.ml b/src/bap_cmdline_terms.ml
index 029479440..414f6e2f9 100644
--- a/src/bap_cmdline_terms.ml
+++ b/src/bap_cmdline_terms.ml
@@ -200,8 +200,113 @@ let no_auto_load, no_auto_load_doc =
   Arg.(value & flag & info ["disable-autoload"] ~doc), doc
 
 
+let recipe_doc = [
+  `S "RECIPE DESCRIPTION";
+  `P "A recipe is either a single file or a directory (optionally
+    zipped) that contains a parametrized specification of command
+    line parameters and support files if necessary.";
+
+  `P
+    "The purpose of the recipe is to make bap runs reproducible, so
+    that you can share one simple file - the recipe, instead of a
+    bunch of scripts together with some verbal instructions. Since
+    recipes introduce an extra layer of abstraction they actually
+    simplify interaction with bap by hiding unnecessary
+    details. Recipes also provide a mechanism for building ready
+    solutions and sharing them with users.";
+
+  `P
+    "To use a recipe, just specify its name using the $(b,--recipe)
+    command line parameter. If a recipe has parameters then they could
+    be specified as colon separated list of $(b,<key>=<value>)
+    pairs. See the $(b,--recipe) parameter for more information. To
+    read the recipe description, including the list of parameters and
+    resulting command line, use the $(b,--show-recipe) command line
+    option. To list all installed recipes use the $(b,--list-recipes)
+    option.";
+
+  `P
+    "The main (and the only necessary) part of a recipe is the recipe
+    specification, that is a file that contains a list of recipe items
+    in an arbitrary order. Each item is either a command line
+    option, a parameter, or a reference to another recipe. All items
+    share the same syntax - they are flat s-expressions, i.e., a
+    whitespace separated list of strings enclosed in parentheses. The
+    first string in the lists denotes the type of the item. E.g.,
+    $(b,(option run-entry-points malloc calloc free)).";
+
+  `P
+    "The $(b,option) command requires one mandatory parameter, the
+    option name, and an arbitrary number of arguments that will be
+    passed to the corresponding command line option. If there are more
+    than one argument then they will be concatenated with the comman
+    symbol, e.g., $(b,(option opt a b c d)) will be translated to
+    $(b,--opt=a,b,c,d). Option arguments may contain substitution
+    symbols. A subsitution symbol starts with the dollar sign, that is
+    followed by a named (optionally delimited with curly braces, to
+    disambiguate it from the rest of the argument). There is one built
+    in parameter called $(b,prefix), that is substituted with the path
+    to the recipe top folder. See the $(b,parameter) command to learn
+    how to introduce parameters.";
+
+  `P
+    "The parameter command introduces a parameter to the recipe, i.e.,
+    a variable ingredient that could be changed when the recipe is
+    used. The parameter command has 3 arguments, all required. The
+    first argument is the parameter name, the second is the default
+    value, that is used if the a parameter wasn't set, and the last
+    argument is the parameter description.  The substitution symbol
+    will be replaced with the default value of a parameter, if a value
+    of the parameter wasn't passed through the command line. Example,";
+
+  `Pre {|
+    (parameter depth 128 "maximum depth of analysis")
+    (option analysis-depth $depth)
+   |};
+
+  `P "
+    If the parameter is not set through the command line, then it will
+    be substituted with $(b,128) otherwise it will receive whatever
+    value a user has passed.
+
+    Finally, the $(b,extend) command is like the include statement in
+    the C preprocessor as it includes all the ingredients from another
+    recipe. (Make sure that you're not introducing loops!). The
+    command has one mandatory argument, the name of the recipe to
+    include.";
+  `S "RECIPE GRAMMAR";
+  `Pre "
+    recipe ::= {<recipe-item>}
+    recipe-item ::= <option> | <parameter> | <extend>
+    option ::= (option <atom> {<atom>})
+    parameter ::= (parameter <atom> <atom> <atom>)
+    extend ::= (extend <atom>)
+"
+]
+
 let recipe =
-  let doc = "Load the specified recipe" in
+  let doc =
+    "Load the specified recipe. The $(docv) parameter specifies the
+  name of the recipe along with an optional colon separated list of
+  arguments. The $(docv) parameter has the following syntax:
+  $(b,<name> : <arg1>=<val1> : <arg2>=<val2> : ...).
+
+  The $(b,<name>) part could be either a path to a valid
+  recipe or the name of a recipe, that would be search in the recipe
+  search paths. A name may omit $(b,.recipe) or $(b,.scm) extensions
+  for brevity.
+
+  The valid representations of a recipe is either the recipe file
+  itself (i.e., a file consisting of a list of s-expressions), a
+  directory with a valid $(recipe.scm) file, or zip file, that
+  contains a valid recipe directory. See the $(b,RECIPES) section for
+  more information.
+
+  If a recipe is a zip file then it will be unpacked to a temporary
+  folder that will be removed after the program terminates. Otherwise,
+  all recipe resources will be used as is and won't be restored to
+  their previous state, e.g., if the input/output files were provided,
+  and they were modified, the modifications will persist." in
   Arg.(value & opt (some string) None & info ["recipe"] ~doc)
 
 let loader_options = [
diff --git a/src/bap_cmdline_terms.mli b/src/bap_cmdline_terms.mli
index 5bc04de07..6c1fe65ee 100644
--- a/src/bap_cmdline_terms.mli
+++ b/src/bap_cmdline_terms.mli
@@ -28,3 +28,4 @@ val recipe : string option Term.t
 val loader_options : string list
 val common_loader_options : Manpage.block list
 val options_for_passes    : Manpage.block list
+val recipe_doc : Manpage.block list
diff --git a/src/bap_main.ml b/src/bap_main.ml
index c5a7b7010..449bc8f61 100644
--- a/src/bap_main.ml
+++ b/src/bap_main.ml
@@ -192,6 +192,7 @@ let program_info =
     `I ("$(b,--list-formats)", Bap_cmdline_terms.list_formats_doc)
   ] @ Bap_cmdline_terms.common_loader_options
     @ Bap_cmdline_terms.options_for_passes
+    @ Bap_cmdline_terms.recipe_doc
     @ [
       `S "BUGS";
       `P "Report bugs to \
@@ -260,9 +261,16 @@ let eval_recipe name =
 
 
 let print_recipe r =
-  printf "%s@\nRecipe Arguments: %s@\n"
-    (Recipe.descr r)
-    (String.concat_array ~sep:" " (Recipe.argv r))
+  printf "DESCRIPTION@\n@\n%s@\n@\n" (Recipe.descr r);
+  let params = Recipe.params r in
+  if params <> [] then begin
+    printf "PARAMETERS@\n@\n";
+    List.iter params ~f:(printf "- %a@\n" Recipe.pp_param);
+    printf "@\n";
+  end;
+  let args = Recipe.argv r in
+  let sep = if Array.length args > 4 then " \\\n" else " " in
+  printf "COMMAND LINE@\n@\n%s@\n" (String.concat_array ~sep args)
 
 let summary str =
   match String.index str '\n' with
@@ -281,7 +289,8 @@ let print_recipes_and_exit () =
             let name = Filename.chop_suffix file ".recipe" in
             match Recipe.load ~paths:recipe_paths name with
             | Ok r ->
-              printf "%-32s %s\n" name (summary (Recipe.descr r));
+              printf "%-32s %s\n" (Filename.basename name)
+                (summary (Recipe.descr r));
               Recipe.cleanup r
             | Error err ->
               eprintf "Malformed recipe %s: %a@\n%!" file
diff --git a/src/bap_recipe.ml b/src/bap_recipe.ml
index ded518944..9f02ca917 100644
--- a/src/bap_recipe.ml
+++ b/src/bap_recipe.ml
@@ -1,17 +1,24 @@
 open Core_kernel.Std
+open Bap.Std
 open Result.Monad_infix
 open Format
 
+include Self()
+
 exception Bad_substitution of string
 
+type format = Zip | Dir | Raw
+
 type error =
   | Expect_atom of Sexp.t list
   | Expect_var of string
   | Bad_item of Sexp.t
+  | Bad_param of string
   | Missing_entry of string
   | Bad_sexp of Parsexp.Parse_error.t
   | No_recipe of string
   | Bad_subst of string
+  | Unbound_param of string
   | Duplicate_var of string
   | Malformed_recipe of string * string * string
   | System_error of string
@@ -35,16 +42,25 @@ type spec = {
   pars : param list;
 }
 
+type entry = {path : string;}
+
 type env = {
   vars : string String.Map.t;
   paths : string list;
 }
 
+type workspace = {
+  path : string;
+  temp : bool;
+  main : string;
+}
+
 type t = {
-  files : string String.Map.t;
+  root  : workspace;
+  args : string list;
   descr : string;
+  spec : spec;
   loads : t list;
-  args : string list;
 }
 
 
@@ -65,6 +81,8 @@ let item_of_sexp = function
     ] -> Ok (Par {name;defl;desc})
   | Sexp.List (Sexp.Atom "option" :: Sexp.Atom name :: args) ->
     atoms args >>| fun args -> Opt (name, args)
+  | Sexp.List (Sexp.Atom "parameter" :: Sexp.Atom s :: _) ->
+    Error (Bad_param s)
   | x -> Error (Bad_item x)
 
 
@@ -77,10 +95,13 @@ let spec_of_items items =
       | Par x -> `Trd x) in
   {uses; opts; pars}
 
-let input files file parse =
-  match Map.find files file with
-  | None -> Error (Missing_entry file)
-  | Some name -> parse (In_channel.read_all name)
+let (/) = Filename.concat
+
+let input file parse root =
+  let path = root.path / file in
+  if Sys.file_exists path
+  then parse (In_channel.read_all path)
+  else Error (Missing_entry file)
 
 let parse_recipe str =
   match Parsexp.Many.parse_string str with
@@ -89,60 +110,111 @@ let parse_recipe str =
 
 let parse_descr str = Ok str
 
-let (/) = Filename.concat
-
-let make_path path name =
-  path / sprintf "%s.recipe" name
+let get_recipe w = input w.main parse_recipe w
+let get_descr w = match input "descr" parse_descr w with
+  | Error (Missing_entry _) -> Ok "Description was not provided"
+  | x -> x
 
 let subst_string f str =
   let buf = Buffer.create (String.length str) in
   Buffer.add_substitute buf f str;
   Buffer.contents buf
 
-let make_subst files pars vars arg =
-  match Map.find files arg with
-  | Some x -> x
-  | None ->  match Map.find vars arg with
+let make_subst root pars vars arg =
+  if arg = "prefix" then root.path
+  else match Map.find vars arg with
     | Some x -> x
     | None -> List.find_map pars ~f:(fun {name; defl} ->
         if name = arg then Some defl else None) |> function
               | Some x -> x
-              | None -> try Sys.getenv arg with
-                | Not_found -> raise (Bad_substitution arg)
+              | None -> raise (Bad_substitution arg)
 
-let apply_subst_exn files pars vars opts =
-  let subst = make_subst files pars vars in
+let apply_subst_exn root pars vars opts =
+  let subst = make_subst root pars vars in
   List.map opts ~f:(fun (name,args) ->
       "--"^name,List.map args ~f:(subst_string subst))
 
-let apply_subst files pars vars opts =
-  try Ok (apply_subst_exn files pars vars opts)
+let apply_subst root pars vars opts =
+  try Ok (apply_subst_exn root pars vars opts)
   with Bad_substitution s -> Error (Bad_subst s)
 
-let linearize  =
-  List.concat_map ~f:(fun (name,xs) -> name :: xs)
+let linearize =
+  List.map ~f:(fun (name,xs) -> match xs with
+      | [] -> name
+      | xs -> String.concat ~sep:"=" [
+          name;
+          String.concat ~sep:"," xs
+        ])
+
+let rng = Caml.Random.State.make_self_init ()
+
+let mkdtemp ?(mode=0o0700) ?tmp_dir ?(prefix="") ?(suffix="") () =
+  let genname () = Uuidm.v4_gen rng () |> Uuidm.to_string in
+  let rec create name =
+    let tmp = match tmp_dir with
+      | None -> Filename.get_temp_dir_name ()
+      | Some tmp -> tmp in
+    let path =
+      String.concat [tmp; Filename.dir_sep; prefix; name; suffix] in
+    match Unix.mkdir path mode with
+    | () -> path
+    | exception Unix.Unix_error(Unix.EEXIST,_,_) ->
+      genname () |> create in
+  genname () |> create
+
+let unzip file dst =
+  let zip = Zip.open_in file in
+  Zip.entries zip |> List.filter ~f:(fun entry -> not entry.is_directory) |>
+  List.iter ~f:(fun ({filename} as entry) ->
+      let path = dst / filename in
+      FileUtil.mkdir ~parent:true (Filename.dirname path);
+      Zip.copy_entry_to_file zip entry path);
+  Zip.close_in zip
+
+let is_zip path =
+  Sys.is_directory path ||
+  try Zip.close_in (Zip.open_in path); true with Zip.Error _ -> false
+
+let target_format t =
+  if Sys.is_directory t then Dir
+  else if is_zip t then Zip else Raw
+
+let read t = match target_format t with
+  | Zip ->
+    let path = mkdtemp ~prefix:"recipe-" ~suffix:".unzipped" () in
+    unzip t path;
+    {path; temp=true; main="recipe.scm"}
+  | Raw -> {path=Filename.dirname t; temp=false; main=t}
+  | Dir -> {path=t; temp=false; main="recipe.scm"}
+
+let check_vars env spec loads =
+  let specs = spec :: List.map loads ~f:(fun s -> s.spec) in
+  Map.keys env |> List.find ~f:(fun arg ->
+      not (List.exists specs ~f:(fun {pars} ->
+          List.exists pars ~f:(fun par ->
+              par.name = arg)))) |> function
+  | None -> Ok ()
+  | Some x -> Error (Unbound_param x)
 
 let rec load_path env path =
-  let zip = Zip.open_in path in
-  let files =
-    List.fold ~init:String.Map.empty (Zip.entries zip)
-      ~f:(fun files ({filename} as entry) ->
-          let tmp,out = Filename.open_temp_file "bap" filename in
-          Zip.copy_entry_to_channel zip entry out;
-          Out_channel.close out;
-          Map.add files ~key:filename ~data:tmp) in
-  input files "descr" parse_descr >>= fun descr ->
-  input files "recipe.scm" parse_recipe >>= fun spec ->
+  let root = read path in
+  get_descr root >>= fun descr ->
+  get_recipe root >>= fun spec ->
   List.map spec.uses ~f:(load env) |> Result.all >>= fun loads ->
-  apply_subst files spec.pars env.vars spec.opts >>| fun args ->
-  {files; descr; loads; args = linearize args}
+  check_vars env.vars spec loads >>= fun () ->
+  apply_subst root spec.pars env.vars spec.opts >>| fun args ->
+  {root; descr; spec; loads; args = linearize args}
 and load env name =
-  List.find env.paths ~f:(fun p ->
-      Sys.file_exists p &&
-      Sys.is_directory p &&
-      Sys.file_exists (make_path p name)) |> function
+  List.find_map env.paths ~f:(fun p ->
+      if Sys.file_exists p && Sys.is_directory p
+      then List.find ~f:Sys.file_exists [
+          p / name;
+          p / name ^ ".scm";
+          p / name ^ ".recipe";
+        ]
+      else None) |> function
   | None -> Error (No_recipe name)
-  | Some parent -> load_path env (make_path parent name)
+  | Some path -> load_path env path
 
 
 let parse_var str =
@@ -151,20 +223,16 @@ let parse_var str =
   | _ -> Error (Expect_var str)
 
 let parse_vars vars =
-  match vars with
-  | None -> Ok (String.Map.empty)
-  | Some vars ->
-    String.split vars ~on:',' |>
-    List.map ~f:parse_var |> Result.all >>= fun vars ->
-    match String.Map.of_alist vars with
-    | `Ok v -> Ok v
-    | `Duplicate_key s -> Error (Duplicate_var s)
+  List.map vars ~f:parse_var |> Result.all >>= fun vars ->
+  match String.Map.of_alist vars with
+  | `Ok v -> Ok v
+  | `Duplicate_key s -> Error (Duplicate_var s)
 
 
 let load_exn ?(paths=[]) name =
   let name,vars = match String.split name ~on:':' with
-    | [name;vars] -> name, Some vars
-    | _ -> name, None in
+    | [] -> failwith "Recipe.load: an empty name was passed"
+    | name :: vars -> String.strip name, vars in
   parse_vars vars >>= fun vars ->
   load {paths; vars} name
 
@@ -183,10 +251,17 @@ let rec args t =
 
 let argv t = Array.of_list (args t)
 
-let descr t = t.descr
+let rec params t = t.spec.pars @ List.concat_map t.loads ~f:params
+
+let descr t =
+  t.descr
+
+let pp_param ppf {name;defl;desc} =
+  fprintf ppf "%s - %s (defaults to %s)" name desc defl
 
 let rec cleanup t =
-  Map.iter t.files ~f:Sys.remove;
+  if t.root.temp
+  then FileUtil.rm ~force:FileUtil.Force ~recurse:true [t.root.path];
   List.iter t.loads ~f:cleanup
 
 let pp_error ppf = function
@@ -194,20 +269,25 @@ let pp_error ppf = function
     fprintf ppf "Parse error: expected an atom got (%a)"
       (pp_print_list Sexp.pp_hum) sexp
   | Expect_var s ->
-    fprintf ppf "Parse error: bad variable, got %s" s
+    fprintf ppf "Parse error: bad variable definition, got `%s'" s
   | Bad_item s ->
     fprintf ppf "Parse error: unknown recipe item - %a" Sexp.pp_hum s
   | Missing_entry s ->
-    fprintf ppf "There required file %s is missing" s
+    fprintf ppf "The required file `%s' is missing" s
   | Bad_sexp err ->
     fprintf ppf "Parse error: %s" (Parsexp.Parse_error.message err)
   | No_recipe r ->
-    fprintf ppf "Can't find the required recipe %s" r
+    fprintf ppf "Can't find the required recipe `%s'" r
   | Bad_subst v ->
-    fprintf ppf "Don't know how to substitute %s" v
+    fprintf ppf "Don't know how to substitute $%s" v
   | Malformed_recipe (x,y,z) ->
     fprintf ppf "Malformed recipe: %s, %s, %s" x y z
   | Duplicate_var s ->
     fprintf ppf "Variable %s was specified twice" s
+  | Bad_param s ->
+    fprintf ppf "Syntax error in the parameter `%s' specification. \
+                 Expecting: (parameter <name> <value> <desc>)" s
+  | Unbound_param s ->
+    fprintf ppf "Unknown parameter `%s'" s
   | System_error s ->
     fprintf ppf "System error: %s" s
diff --git a/src/bap_recipe.mli b/src/bap_recipe.mli
index 8e5b6fb30..3b7e3bbba 100644
--- a/src/bap_recipe.mli
+++ b/src/bap_recipe.mli
@@ -3,13 +3,12 @@ open Core_kernel.Std
 type error
 
 type t
+type param
 
 val load : ?paths:string list -> string -> (t,error) result
-
 val argv : t -> string array
-
 val cleanup : t -> unit
-
 val descr : t -> string
-
+val params : t -> param list
 val pp_error : Format.formatter -> error -> unit
+val pp_param : Format.formatter -> param -> unit