DannyBen · DannyBen · Jul 9, 2026 · Jul 9, 2026
diff --git a/README.md b/README.md
@@ -72,22 +72,26 @@ Implemented pieces include:
 
 ### Gherkin Feature Support
 
-| Feature                  | Status      |
-|:-------------------------|:------------|
-| `Feature`                | Supported   |
-| Feature description text | Supported   |
-| `Scenario`               | Supported   |
-| `Background`             | Supported   |
-| `Given`, `When`, `Then`  | Supported   |
-| `And` , `But`            | Supported   |
-| `*` step keyword         | Supported   |
-| Doc strings (`"""`)      | Supported   |
-| Comments (`#`)           | Supported   |
-| `Rule`                   | Unsupported |
-| `Scenario Outline`       | Unsupported |
-| `Examples`               | Unsupported |
-| Data tables              | Unsupported |
-| Tags (`@tag`)            | Unsupported |
+| Feature                       | Status      |
+|:------------------------------|:------------|
+| `Feature`                     | Supported   |
+| Feature description text      | Supported   |
+| `Scenario`                    | Supported   |
+| `Background`                  | Supported   |
+| `Given`, `When`, `Then`       | Supported   |
+| `And` , `But`                 | Supported   |
+| `*` step keyword              | Supported   |
+| Doc strings (`"""`)           | Supported   |
+| Comments (`#`)                | Supported   |
+| Tags (`@tag`)                 | Supported   |
+| `Rule`                        | Unsupported |
+| `Scenario Outline`            | Unsupported |
+| `Examples`                    | Unsupported |
+| Data tables                   | Unsupported |
+| `Before`, `After` hooks       | Unsupported |
+| `BeforeAll`, `AfterAll` hooks | Unsupported |
+
+Tags can be selected with `--tag` / `-t` and skipped with `--exclude-tag` / `-x`.
 
 ## Usage
 
@@ -104,6 +108,12 @@ shellkin --validate
 # Stop after the first failing scenario:
 shellkin --fail-fast
 
+# Run scenarios tagged @smoke:
+shellkin -t @smoke
+
+# Skip scenarios tagged @slow:
+shellkin -x @slow
+
 # Run a specific directory:
 shellkin path/to/features
 

diff --git a/doc/shellkin-feature.5 b/doc/shellkin-feature.5
@@ -91,6 +91,23 @@ Lines starting with \f[B]#\f[R] are treated as comments.
 # This is a comment
 Feature: Example
 .EE
+.SH TAGS
+Tags can be placed before a \f[B]Feature:\f[R] or \f[B]Scenario:\f[R].
+.IP
+.EX
+\(atfilesystem
+Feature: Files
+
+\(atsmoke
+Scenario: Create a file
+  When I run \(aqtouch one\(aq
+  Then the file \(aqone\(aq should exist
+.EE
+.PP
+Feature tags are inherited by the scenarios in that feature.
+Use \f[B]shellkin \-\-tag \(attag\f[R] to run scenarios with a tag, and
+\f[B]shellkin \-\-exclude\-tag \(attag\f[R] to skip scenarios with a
+tag.
 .SH DOC STRINGS
 Shellkin supports Gherkin\-style doc strings using
 \f[B]\(dq\(dq\(dq\f[R] fences.
@@ -118,7 +135,7 @@ The following common Gherkin constructs are not currently supported:
 .IP \(bu 2
 data tables
 .IP \(bu 2
-tags such as \f[B]\(atslow\f[R]
+hooks
 .SH EXAMPLE
 .IP
 .EX

diff --git a/doc/shellkin-feature.md b/doc/shellkin-feature.md
@@ -116,6 +116,25 @@ Lines starting with **#** are treated as comments.
 Feature: Example
 ```
 
+TAGS
+==================================================
+
+Tags can be placed before a **Feature:** or **Scenario:**.
+
+```gherkin
+@filesystem
+Feature: Files
+
+@smoke
+Scenario: Create a file
+  When I run 'touch one'
+  Then the file 'one' should exist
+```
+
+Feature tags are inherited by the scenarios in that feature. Use
+**shellkin --tag @tag** to run scenarios with a tag, and
+**shellkin --exclude-tag @tag** to skip scenarios with a tag.
+
 DOC STRINGS
 ==================================================
 
@@ -143,7 +162,7 @@ The following common Gherkin constructs are not currently supported:
 - **Scenario Outline**
 - **Examples**
 - data tables
-- tags such as **@slow**
+- hooks
 
 EXAMPLE
 ==================================================

diff --git a/doc/shellkin.1 b/doc/shellkin.1
@@ -32,19 +32,32 @@ Conflicts With: \f[B]\-\-init\f[R]
 .SS \-\-validate, \-v
 Validate feature and step definition files
 .IP \(bu 2
-Conflicts With: \f[B]\-\-init\f[R]
+Conflicts With: \f[B]\-\-init, \-\-tag, \-\-exclude\-tag\f[R]
 .SS \-\-init
 Initialize a Shellkin features directory
 .IP \(bu 2
-Conflicts With: \f[B]\-\-validate, \-\-fail\-fast, \-\-load\f[R]
-.SS \-\-default\-target, \-t DIR
+Conflicts With: \f[B]\-\-validate, \-\-fail\-fast, \-\-load, \-\-tag,
+\-\-exclude\-tag\f[R]
+.SS \-\-default\-target DIR
 Path to features directory
 .PP
 Relative to working directory
 .PP
 Normally only used in a .shellkin argfile
 .IP \(bu 2
 Default Value: \f[B]features\f[R]
+.SS \-\-tag, \-t TAG
+Run scenarios with this tag
+.IP \(bu 2
+\f[I]Repeatable\f[R]
+.IP \(bu 2
+Conflicts With: \f[B]\-\-init, \-\-validate\f[R]
+.SS \-\-exclude\-tag, \-x TAG
+Skip scenarios with this tag
+.IP \(bu 2
+\f[I]Repeatable\f[R]
+.IP \(bu 2
+Conflicts With: \f[B]\-\-init, \-\-validate\f[R]
 .SS \-\-stepdefs, \-s DIR
 Path to step definitions directory
 .PP

diff --git a/doc/shellkin.md b/doc/shellkin.md
@@ -53,16 +53,16 @@ Abort after the first failing scenario
 
 Validate feature and step definition files
 
-- Conflicts With: **--init**
+- Conflicts With: **--init, --tag, --exclude-tag**
 
 --init
 --------------------------------------------------
 
 Initialize a Shellkin features directory
 
-- Conflicts With: **--validate, --fail-fast, --load**
+- Conflicts With: **--validate, --fail-fast, --load, --tag, --exclude-tag**
 
---default-target, -t DIR
+--default-target DIR
 --------------------------------------------------
 
 Path to features directory
@@ -74,6 +74,22 @@ Normally only used in a .shellkin argfile
 
 - Default Value: **features**
 
+--tag, -t TAG
+--------------------------------------------------
+
+Run scenarios with this tag
+
+- *Repeatable*
+- Conflicts With: **--init, --validate**
+
+--exclude-tag, -x TAG
+--------------------------------------------------
+
+Skip scenarios with this tag
+
+- *Repeatable*
+- Conflicts With: **--init, --validate**
+
 --stepdefs, -s DIR
 --------------------------------------------------
 

diff --git a/features/fixtures/features/one.feature b/features/fixtures/features/one.feature
@@ -1,6 +1,7 @@
 Feature: one
   Passing fixture
 
+@smoke
 Scenario: one passes
   When I run 'printf one'
   Then the output should include 'one'
diff --git a/features/fixtures/features/two.feature b/features/fixtures/features/two.feature
@@ -1,6 +1,7 @@
 Feature: two
   Another passing fixture
 
+@smoke @slow
 Scenario: two passes
   When I run 'printf two'
   Then the output should include 'two'
diff --git a/features/help.feature b/features/help.feature
@@ -5,3 +5,6 @@ Scenario: Run --help
   When I run 'shellkin --help'
   Then the output should include 'shellkin [TARGET] [OPTIONS]'
    And the output should include '--fail-fast, -f'
+   And the output should include '--default-target DIR'
+   And the output should include '--tag, -t'
+   And the output should include '--exclude-tag, -x'
diff --git a/features/test.feature b/features/test.feature
@@ -7,6 +7,13 @@ Scenario: Running all feature tests
    And the output should include '3 scenarios, 0 failing'
    And the exit code should mean success
 
+Scenario: Filtering scenarios by tag
+  When I run 'shellkin -t @smoke -x @slow features/fixtures/features'
+  Then the output should include 'Feature: one'
+  And the output should include 'Scenario 2: one passes'
+  And the output should include '1 scenario, 0 failing'
+  And the exit code should mean success
+
 Scenario: Running a failing test
   When I run 'shellkin features/fixtures/selective/failing.feature'
   Then the output should include 'Feature: two'