Diff
1diff --git a/README.md b/README.md
2new file mode 100644
3index 0000000000000000000000000000000000000000..b73c23f2700d79e83a7a1d117c87b6b9ae6c3b23
4--- /dev/null
5+++ b/README.md
6@@ -0,0 +1,72 @@
7+# logfmt CLI
8+
9+This is a (very) simple logfmt CLI tool to make reading logfmt logs on your terminal easier.
10+It supports colorized output, output field selection, and log level and key value filtering.
11+
12+## What is logfmt?
13+
14+[logfmt](https://www.brandur.org/logfmt) is a basic structured logging format that uses key=value pairs. It is
15+most popular in go apps, due to its simplicity, and ease of reading and parsing. However, printing logfmt
16+formatted logs to the terminal and trying to find what you are looking for can be difficult, especially when there's a
17+lot of debug keys like `source`, `function`, `caller`, etc. The fact that its all white on black (or black on white if
18+you hate your retinas) doesn't help either.
19+
20+### The solution
21+
22+The goal of this tool is to make these logs more readable by applying some syntax highlighting, separating the
23+`timestamp` and `level` fields into static locations without their keys, filtering based on log level, picking specific
24+output columns, and filtering based on specific key=value pairs (say you're looking only for a specific API call).
25+
26+## How to
27+
28+### Installation
29+
30+I recommend adding a `GOBIN` env var to your shell with a location to where you want go compiled programs to reside
31+and adding that location to your `PATH`. With that set up, you can install logfmt using:
32+
33+```
34+go install github.com/TheEdgeOfRage/logfmt
35+```
36+
37+### Usage
38+
39+```
40+Usage:
41+ logfmt [OPTIONS]
42+
43+Application Options:
44+ -l, --level= Log level filter. One of DEBUG, INFO, WARN, ERROR, FATAL (default: INFO)
45+ -o, --output= Output field selector (comma separated)
46+ -f, --filter= Filter fields (key=value comma separated)
47+ -n, --no-color Disable color output
48+
49+Help Options:
50+ -h, --help Show this help message
51+```
52+
53+If installed in your PATH, you can just run the `logfmt` program without any arguments and it will start reading log
54+lines from stdin and write the formatted lines to stdout.
55+
56+This CLI follows the UNIX philosophy, so it will only read from stdin and write to stdout. If you want stderr or a different
57+file, use your shell's built-in directives for that.
58+
59+#### Level filtering
60+
61+To filters your logs based on the log level, you can pass the `-l` flag with a log level in CAPS format. The level you
62+provide is lowest level that will get printed, so if you set it to `WARN`, only `WARN`, `ERROR`, and `FATAL` logs will
63+show up.
64+
65+#### Output field selection
66+
67+You can pass in a comma separated list of fields to the `-o` flag that you want it to print to the output. The timestamp
68+and level are always printed, so this only applies to additional fields.
69+
70+#### Filtering by values
71+
72+If you want to only select records that have a specific value on a key, you can pass one or more comma separated filters
73+to the `-f` flag in the `key=value` format. Only log lines that match all the filters exactly will be printed. Regex or
74+numerical filtering might come in the future.
75+
76+#### No color
77+
78+If you don't want to have colors on the output, use `-n`.