diff --git a/README.md b/README.md
index 64a3683153..bf9e890c0e 100644
--- a/README.md
+++ b/README.md
@@ -36,10 +36,10 @@ $ swarm create
 # on each of your nodes, start the swarm agent
 #  <node_ip> doesn't have to be public (eg. 192.168.0.X),
 #  as long as the other nodes can reach it, it is fine.
-$ swarm join --discovery token://<cluster_id> --addr=<node_ip:2375>
+$ swarm join --addr=<node_ip:2375> token://<cluster_id>
 
 # start the manager on any machine or your laptop
-$ swarm manage --discovery token://<cluster_id> -H tcp://<swarm_ip:swarm_port>
+$ swarm manage -H tcp://<swarm_ip:swarm_port> token://<cluster_id>
 
 # use the regular docker cli
 $ docker -H tcp://<swarm_ip:swarm_port> info
@@ -49,7 +49,7 @@ $ docker -H tcp://<swarm_ip:swarm_port> logs ...
 ...
 
 # list nodes in your cluster
-$ swarm list --discovery token://<cluster_id>
+$ swarm list token://<cluster_id>
 <node_ip:2375>
 ```
 
diff --git a/discovery/README.md b/discovery/README.md
index b89a3a8def..45f498e16c 100644
--- a/discovery/README.md
+++ b/discovery/README.md
@@ -15,10 +15,10 @@ $ swarm create
 # on each of your nodes, start the swarm agent
 #  <node_ip> doesn't have to be public (eg. 192.168.0.X),
 #  as long as the other nodes can reach it, it is fine.
-$ swarm join --discovery token://<cluster_id> --addr=<node_ip:2375>
+$ swarm join --addr=<node_ip:2375> token://<cluster_id>
 
 # start the manager on any machine or your laptop
-$ swarm manage --discovery token://<cluster_id> -H tcp://<swarm_ip:swarm_port>
+$ swarm manage -H tcp://<swarm_ip:swarm_port> token://<cluster_id>
 
 # use the regular docker cli
 $ docker -H tcp://<swarm_ip:swarm_port> info
@@ -28,7 +28,7 @@ $ docker -H tcp://<swarm_ip:swarm_port> logs ...
 ...
 
 # list nodes in your cluster
-$ swarm list --discovery token://<cluster_id>
+$ swarm list token://<cluster_id>
 <node_ip:2375>
 ```
 
@@ -43,7 +43,7 @@ $ echo <node_ip2:2375> >> /tmp/my_cluster
 $ echo <node_ip3:2375> >> /tmp/my_cluster
 
 # start the manager on any machine or your laptop
-$ swarm manage --discovery file:///tmp/my_cluster -H tcp://<swarm_ip:swarm_port>
+$ swarm manage -H tcp://<swarm_ip:swarm_port> file:///tmp/my_cluster
 
 # use the regular docker cli
 $ docker -H tcp://<swarm_ip:swarm_port> info
@@ -53,7 +53,7 @@ $ docker -H tcp://<swarm_ip:swarm_port> logs ...
 ...
 
 # list nodes in your cluster
-$ swarm list --discovery file:///tmp/my_cluster
+$ swarm list file:///tmp/my_cluster
 <node_ip1:2375>
 <node_ip2:2375>
 <node_ip3:2375>
@@ -65,10 +65,10 @@ $ swarm list --discovery file:///tmp/my_cluster
 # on each of your nodes, start the swarm agent
 #  <node_ip> doesn't have to be public (eg. 192.168.0.X),
 #  as long as the other nodes can reach it, it is fine.
-$ swarm join --discovery etcd://<etcd_ip>/<path> --addr=<node_ip:2375>
+$ swarm join --addr=<node_ip:2375> etcd://<etcd_ip>/<path>
 
 # start the manager on any machine or your laptop
-$ swarm manage --discovery etcd://<etcd_ip>/<path> -H tcp://<swarm_ip:swarm_port>
+$ swarm manage -H tcp://<swarm_ip:swarm_port> etcd://<etcd_ip>/<path>
 
 # use the regular docker cli
 $ docker -H tcp://<swarm_ip:swarm_port> info
@@ -78,7 +78,7 @@ $ docker -H tcp://<swarm_ip:swarm_port> logs ...
 ...
 
 # list nodes in your cluster
-$ swarm list --discovery etcd://<etcd_ip>/<path>
+$ swarm list etcd://<etcd_ip>/<path>
 <node_ip:2375>
 ```
 
@@ -88,10 +88,10 @@ $ swarm list --discovery etcd://<etcd_ip>/<path>
 # on each of your nodes, start the swarm agent
 #  <node_ip> doesn't have to be public (eg. 192.168.0.X),
 #  as long as the other nodes can reach it, it is fine.
-$ swarm join --discovery consul://<consul_addr>/<path> --addr=<node_ip:2375>
+$ swarm join --addr=<node_ip:2375> consul://<consul_addr>/<path>
 
 # start the manager on any machine or your laptop
-$ swarm manage --discovery consul://<consul_addr>/<path> -H tcp://<swarm_ip:swarm_port>
+$ swarm manage -H tcp://<swarm_ip:swarm_port> consul://<consul_addr>/<path>
 
 # use the regular docker cli
 $ docker -H tcp://<swarm_ip:swarm_port> info
@@ -101,7 +101,7 @@ $ docker -H tcp://<swarm_ip:swarm_port> logs ...
 ...
 
 # list nodes in your cluster
-$ swarm list --discovery consul://<consul_addr>/<path>
+$ swarm list consul://<consul_addr>/<path>
 <node_ip:2375>
 ```
 
@@ -111,10 +111,10 @@ $ swarm list --discovery consul://<consul_addr>/<path>
 # on each of your nodes, start the swarm agent
 #  <node_ip> doesn't have to be public (eg. 192.168.0.X),
 #  as long as the other nodes can reach it, it is fine.
-$ swarm join --discovery zk://<zookeeper_addr1>,<zookeeper_addr2>/<path> --addr=<node_ip:2375>
+$ swarm join --addr=<node_ip:2375> zk://<zookeeper_addr1>,<zookeeper_addr2>/<path>
 
 # start the manager on any machine or your laptop
-$ swarm manage --discovery zk://<zookeeper_addr1>,<zookeeper_addr2>/<path> -H tcp://<swarm_ip:swarm_port>
+$ swarm manage -H tcp://<swarm_ip:swarm_port> zk://<zookeeper_addr1>,<zookeeper_addr2>/<path>
 
 # use the regular docker cli
 $ docker -H tcp://<swarm_ip:swarm_port> info
@@ -124,7 +124,7 @@ $ docker -H tcp://<swarm_ip:swarm_port> logs ...
 ...
 
 # list nodes in your cluster
-$ swarm list --discovery zk://<zookeeper_addr1>,<zookeeper_addr2>/<path>
+$ swarm list zk://<zookeeper_addr1>,<zookeeper_addr2>/<path>
 <node_ip:2375>
 ```
 
@@ -132,9 +132,9 @@ $ swarm list --discovery zk://<zookeeper_addr1>,<zookeeper_addr2>/<path>
 
 ```bash
 # start the manager on any machine or your laptop
-$ swarm manage --discovery <node_ip1:2375>,<node_ip2:2375> -H=<swarm_ip:swarm_port>
+$ swarm manage -H <swarm_ip:swarm_port> nodes://<node_ip1:2375>,<node_ip2:2375>
 #or
-$ swarm manage --discovery nodes://<node_ip1:2375>,<node_ip2:2375> -H=<swarm_ip:swarm_port>
+$ swarm manage -H <swarm_ip:swarm_port> nodes://<node_ip1:2375>,<node_ip2:2375>
 
 # use the regular docker cli
 $ docker -H <swarm_ip:swarm_port> info
@@ -159,7 +159,7 @@ type DiscoveryService interface {
 ```
 
 ######Initialize
-take the `--discovery` without the scheme and a heartbeat (in seconds)
+take the `discovery` without the scheme and a heartbeat (in seconds)
 
 ######Fetch
 returns the list of all the nodes from the discovery
diff --git a/flags.go b/flags.go
index f3dbd18108..33fabea961 100644
--- a/flags.go
+++ b/flags.go
@@ -31,12 +31,6 @@ var (
 		Value: homepath(".swarm"),
 		Usage: "",
 	}
-	flDiscovery = cli.StringFlag{
-		Name:   "discovery",
-		Value:  "",
-		Usage:  "discovery service to use [token://<token>,\n\t\t\t\t  etcd://<ip1>,<ip2>/<path>,\n\t\t\t\t  file://path/to/file,\n\t\t\t\t  consul://<addr>/<path>,\n\t\t\t\t  zk://<ip1>,<ip2>/<path>,\n\t\t\t\t  <ip1>,<ip2>]",
-		EnvVar: "SWARM_DISCOVERY",
-	}
 	flAddr = cli.StringFlag{
 		Name:   "addr",
 		Value:  "127.0.0.1:4243",
diff --git a/help.go b/help.go
index cf06c4ab2c..a2b3690239 100644
--- a/help.go
+++ b/help.go
@@ -7,7 +7,7 @@ func init() {
 	cli.CommandHelpTemplate = `{{$DISCOVERY := or (eq .Name "manage") (eq .Name "join") (eq .Name "list")}}NAME:
    {{.Name}} - {{.Usage}}
 USAGE:
-   swarm {{.Name}}{{if .Flags}} [command options]{{end}} {{if $DISCOVERY}}[discovery]{{end}}{{if .Description}}
+   swarm {{.Name}}{{if .Flags}} [options]{{end}} {{if $DISCOVERY}}<discovery>{{end}}{{if .Description}}
 DESCRIPTION:
    {{.Description}}{{end}}{{if $DISCOVERY}}
 ARGUMENTS:
diff --git a/scheduler/filter/README.md b/scheduler/filter/README.md
index fad98b44f5..65c10b8c25 100644
--- a/scheduler/filter/README.md
+++ b/scheduler/filter/README.md
@@ -30,14 +30,14 @@ For instance, let's start `node-1` with the `storage=ssd` label:
 
 ```bash
 $ docker -d --label storage=ssd
-$ swarm join --discovery token://XXXXXXXXXXXXXXXXXX --addr=192.168.0.42:2375
+$ swarm join --addr=192.168.0.42:2375 token://XXXXXXXXXXXXXXXXXX
 ```
 
 Again, but this time `node-2` with `storage=disk`:
 
 ```bash
 $ docker -d --label storage=disk
-$ swarm join --discovery token://XXXXXXXXXXXXXXXXXX --addr=192.168.0.43:2375
+$ swarm join --addr=192.168.0.43:2375 token://XXXXXXXXXXXXXXXXXX
 ```
 
 Once the nodes are registered with the cluster, the master pulls their respective tags and will take them into account when scheduling new containers.