diff --git a/hledger/Hledger/Cli/Commands/Payees.hs b/hledger/Hledger/Cli/Commands/Payees.hs
index 7b0108c13..9a13c98ca 100644
--- a/hledger/Hledger/Cli/Commands/Payees.hs
+++ b/hledger/Hledger/Cli/Commands/Payees.hs
@@ -17,6 +17,7 @@ module Hledger.Cli.Commands.Payees (
 
 import Data.List.Extra (nubSort)
 import qualified Data.Text.IO as T
+import System.Console.CmdArgs.Explicit as C
 
 import Hledger
 import Hledger.Cli.CliOptions
@@ -25,14 +26,24 @@ import Hledger.Cli.CliOptions
 -- | Command line options for this command.
 payeesmode = hledgerCommandMode
   $(embedFileRelative "Hledger/Cli/Commands/Payees.txt")
-  []
+  [flagNone ["declared"] (setboolopt "declared") "show payees declared with payee directives"
+  ,flagNone ["used"] (setboolopt "used") "show payees referenced by transactions"
+  ]
   [generalflagsgroup1]
   hiddenflags
   ([], Just $ argsFlag "[QUERY]")
 
 -- | The payees command.
 payees :: CliOpts -> Journal -> IO ()
-payees CliOpts{reportspec_=rspec} j = do
-  let ts = entriesReport rspec j
-      payees = nubSort $ map transactionPayee ts
+payees CliOpts{rawopts_=rawopts, reportspec_=ReportSpec{rsQuery=query}} j = do
+  let 
+    declared = boolopt "declared" rawopts
+    used     = boolopt "used"     rawopts
+    -- XXX matchesPayee is currently an alias for matchesDescription, not sure if it matters
+    matcheddeclaredpayees = filter (matchesPayeeWIP query) $ journalPayeesDeclared j
+    matchedusedpayees     = map transactionPayee $ filter (matchesTransaction query) $ jtxns j
+    payees = nubSort $
+      if | declared     && not used -> matcheddeclaredpayees
+         | not declared && used     -> matchedusedpayees
+         | otherwise                -> matcheddeclaredpayees ++ matchedusedpayees
   mapM_ T.putStrLn payees
diff --git a/hledger/Hledger/Cli/Commands/Payees.md b/hledger/Hledger/Cli/Commands/Payees.md
index a6031658f..20d35de94 100644
--- a/hledger/Hledger/Cli/Commands/Payees.md
+++ b/hledger/Hledger/Cli/Commands/Payees.md
@@ -3,12 +3,17 @@ List the unique payee/payer names that appear in transactions.
 
 _FLAGS
 
-This command lists the unique payee/payer names that appear in transactions,
-in alphabetic order. 
-You can add a query to select a subset of transactions.
-The payee/payer is the part of the transaction description before a | character
+This command lists unique payee/payer names which have been 
+declared with payee directives (--declared), 
+used in transaction descriptions (--used), 
+or both (the default).
+
+The payee/payer is the part of the transaction description before a | character 
 (or if there is no |, the whole description).
 
+You can add query arguments to select a subset of transactions. This implies --used.
+
+
 Example:
 ```shell
 $ hledger payees
diff --git a/hledger/test/payees.test b/hledger/test/payees.test
index e5d510144..4a5fc8654 100644
--- a/hledger/test/payees.test
+++ b/hledger/test/payees.test
@@ -2,18 +2,32 @@
 
 # basic payees report
 <
-2018/1/1 foo  ; foo:
+payee qux
+
+2018/1/1 foo
   a
 
-2018/1/1 bar | baz
+2018/1/2 bar | baz
   a
 
+2018/1/3 foo
+  a
+
+# declared and used payees, the default
 $ hledger -f - payees
 bar
 foo
->=
+qux
 
-# filtering transactions by tag
-$ hledger -f - payees tag:foo
+# used payees
+$ hledger -f - payees --used
+bar
+foo
+
+# declared payees
+$ hledger -f - payees --declared
+qux
+
+# payees used in transactions matched by a query
+$ hledger -f - payees date:2018-01-03
 foo
->=