README for Tools

Write a README that gets someone from zero to productive in five minutes — install, configure, use, and troubleshoot.

6 min readProgramming Foundations (Go)Code

What a Tool README Needs

A good tool README answers five questions in order: What does this do? How do I install it? How do I use it? How do I configure it? What do I do when it breaks?

One-sentence description at the very top.
Install instructions for every platform you ship binaries for.
Quickstart — the three commands to go from zero to working.
Command reference — every subcommand and flag.
Configuration — every environment variable and config file option.
Troubleshooting — the five most common errors and their fixes.
Contributing — how to build from source and run tests.

Install Section

README: Install section


## Install

### Pre-built binaries (recommended)

Download the latest release for your platform from the
[Releases page](https://github.com/thesyscoder/tasker/releases).

```sh
# macOS / Linux
curl -L https://github.com/thesyscoder/tasker/releases/latest/download/tasker_$(uname -s)_$(uname -m).tar.gz | tar xz
chmod +x tasker
sudo mv tasker /usr/local/bin/

# Verify
tasker --version
```

### Build from source

```sh
git clone https://github.com/thesyscoder/tasker
cd tasker
make build
./tasker --version
```

Usage Examples

Show real, copy-pasteable examples. Show what the output looks like. Cover the common workflows, not every possible flag combination.

README: Usage section


## Usage

```sh
# Add a task
tasker add -title "Review pull request" -tag work -priority high

# List all tasks
tasker list

# List incomplete work tasks
tasker list -tag work -done false

# Mark a task complete
tasker done -id 1234567890

# Delete a task
tasker delete -id 1234567890
```

### JSON output

Add `--json` to any command for machine-readable output:

```sh
tasker list --json | jq '.tasks[] | select(.priority == "high")'
```

Configuration Reference

README: Configuration table


## Configuration

All settings can be provided as environment variables or flags.
Flags take precedence over environment variables.

| Flag          | Environment variable | Default           | Description                   |
|---------------|---------------------|-------------------|-------------------------------|
| `--data-dir`  | `DATA_DIR`          | `~/.tasker`       | Directory for tasks.json      |
| `--log-level` | `LOG_LEVEL`         | `info`            | Log verbosity (debug/info/warn/error) |
| `--log-format`| `LOG_FORMAT`        | `json`            | Log format (json or text)     |
| `--version`   | —                   | —                 | Print version and exit        |

## Troubleshooting

**Permission denied on tasks.json**
Check that `~/.tasker` is owned by your user and has `rwx` permissions:
```sh
ls -la ~/.tasker
chmod 700 ~/.tasker
```

**Unknown command error**
Run `tasker help` to see available subcommands and their flags.

Congratulations — you have shipped a real Go tool

You started from zero — no programming background assumed — and you now have a typed, tested, documented, cross-compiled Go binary with graceful shutdown, structured logging, and atomic file writes. Every pattern in this course appears in real production tools at companies like HashiCorp, Grafana, and Datadog. The fundamentals are complete. From here, every specialization — SRE tooling, Kubernetes operators, HTTP services, data pipelines — is just applying these building blocks to a new domain.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.

Stage 1 · Code

Capstone — Ship a Real Tool