Need help with slurper?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

126 Stars 32 Forks MIT License 137 Commits 2 Opened issues


Gem for slurping plain text stories into Pivotal Tracker

Services available


Need anything else?

Contributors list


Slurper allows you to quickly compose your stories in a text file and import them into Pivotal Tracker.

Works great with slurper.vim!


$ gem install slurper


Slurper requires a

file in your working directory. This file contains your Tracker API and story requestor information.


# slurper_config.yml

project_id: 1234 token: 123abc123abc123abc requested_by: Jane Stakeholder


tells tracker which project to add your stories to. It can be found on the project settings or the URL for the project.


can be found on your personal profile page in Pivotal Tracker.


field should be the name of your project stakeholder exactly as it appears in tracker.


Create a

file and compose your stories in the Slurper story format. In your working directory use the slurp command to import your stories from the
file into Pivotal Tracker. Slurper looks for a
file in your current directory by default; however, you can provide an alternate story source file if necessary.


$ slurp ~/stories.slurper

Also valid

$ slurp ~/special_stories.slurper

Or even

$ slurp ~/mystories.txt

Example Stories

/* stories.slurper */

== story_type: chore name: Set Up Staging Environment description: Set up and configure staging environment for approval of stories

labels: staging == story_type: feature name: Campaign Manager Does Something description: In order to get some value As a campaign manager I want to do something

  • can do something

labels: campaign managers == story_type: release name: Big Release description: This release marks a lot of awesome functionality

labels: campaign managers == story_type: bug name: I did something and nothing happened description: When I do something, another thing is supposed to happen but I see an error screen instead.

labels: campaign managers

Note: the story source file is whitespace-sensitive. Be sure the value for each key phrase is indented with two spaces beneath each key phrase. Also, start each story with a double-equals on its own line.

Your best bet is to leverage slurper.vim and benefit from its auto-indenting goodness.

Example Stories (Advanced)

There are some advanced techniques for formatting your stories beyond the simple type, name, description and label fields. See below for some examples.

/* advanced.slurper */

== story_type: feature name: Make the cart accept coupons on checkout description: When I get to the checkout phase, I want the ability to add an optional coupon code. Use TESTCOUPON to test with. labels: cart,coupon system,checkout estimate: 3 requested_by: Joe Developer

Note: Any field that is supported by the Pivotal Tracker API should work within reason (i.e. file uploads won't work). To get an idea of the fields available see Pivotal Tracker's Example CSV data documentation.


  1. Fork it
  2. Create your feature branch (
    git checkout -b my-new-feature
  3. Commit your changes (
    git commit -am 'Add some feature'
  4. Push to the branch (
    git push origin my-new-feature
  5. Create new Pull Request

Please add tests at the same time as new features, and verify they all pass with:

$ rake

Credit - Wes Gibbs ( thought of and wrote Slurper as a Ruby script. It was later packaged and released as a gem by his fellow Rocketeers after using it and finding it extremely handy.


Hashrocket logo

Slurper is supported by the team at Hashrocket, a multidisciplinary design and development consultancy. If you'd like to work with us or join our team, don't hesitate to get in touch.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.