++ed by:

2 PAUSE users
3 non-PAUSE users.

Paul Jamieson Fenwick


WebService::HabitRPG - Perl interface to the HabitRPG API


version 0.14


    use WebService::HabitRPG;

    # The API Token and User ID are obained through the
    # Setting -> API link on http://habitrpg.com/

    my $hrpg = WebService::HabitRPG->new(
        api_token => 'your-token-goes-here',
        user_id   => 'your-user-id-goes-here',

    # Get everyting about the user
    my $user = $hrpg->user;

    # Get all tasks.
    my $tasks = $hrpg->tasks;

    # Get all tasks of a particular type (eg: 'daily')
    my $daily = $hrpg->tasks('daily');

    # Increment/decrement a task

    # Make a new task
        type => 'daily',
        text => 'floss teeth',
        up   => 1,
        down => 0,


Interface to API provided by HabitRPG.

At the time of release, the HabitRPG API is still under construction. This module may change as a result.

Note that when data structures are returned, they are almost always straight conversions from the JSON returned by the HabitRPG API.



    my $hrpg = WebService::HabitRPG->new(
        api_token => 'your-token-goes-here',
        user_id   => 'your-user-id-goes-here',

Creates a new WebService::HabitRPG object. The api_token and user_id parameters are mandatory. You may also pass your own WWW::Mechanize compatible user-agent with agent, and should you need it your own HabitRPG API base URL with api_base (useful for testing, or if you're running your own server).

By default, the official API base of https://habitrpg.com/api/v1 is used.


    my $user = $hrpg->user();

Returns everything from the /user route in the HabitRPG API. This is practically everything about the user, their tasks, scores, and other information.

The Perl data structure that is returned is a straight conversion from the JSON provided by the HabitRPG API.


    my $tasks  = $hrpg->tasks();            # All tasks
    my $habits = $hrpg->tasks('habit');     # Only habits

Return a reference to an array of tasks. With no arguments, all tasks (habits, dailies, todos and rewards) are returned. With an argument, only tasks of the given type are returned. The argument must be one of habit, daily, todo or reward.

The data returned for each task is defined by the HabitRPG API, but at the time of writing is:

        text    => 'floss', # Text shown in web interface. Task name.
        type    => 'habit', # One of: habit, todo, daily, reward
        id      => '...',   # Internal task ID. Extensively used by API.
        value   => 0,       # Either cost in GP, or how well one is doing
        notes   => '',      # Extended, human-readable note field
        repeat  => {...},   # Daily tasks only. 
        up      => 1,       # Can this task be incremented?
        down    => 0,       # Can this task be decremented?
        history => [...],   # History data for this task.

Not all tasks will have all fields. Using the hrpg command-line tool with hrpg dump tasks is a convenient way to see the data structures returned by this method.


    my $task = $hrpg->get_task('6a11dd4d-c2d6-42b7-b9ff-f562d4ccce4e');

Given a task ID, returns information on that task in the same format at "tasks" above.


        type      => 'daily',           # Required
        text      => 'floss teeth',     # Required
        up        => 1,                 # Suggested, defaults true
        down      => 0,                 # Suggested, defaults true
        value     => 0,
        note      => "Floss every tooth for great justice",
        completed => 0,
        extend    => {},

Creates a new task. Only the type and text arguments are required, all other tasks are optional. The up and down options default to true (ie, tasks can be both incremented and decremented).

The type parameter must be one of: habit, daily, todo or reward.

The extend parameter consists to key/value pairs that will be added to the JSON create packet. This should only be used if you know what you're doing, and wish to take advantage of new or undocumented features in the API.

Returns a task data structure of the task created, identical to the "tasks" method above.

Creating tasks that can be neither incremented nor decremented is of dubious usefulness.


    $hrpg->updown('6a11dd4d-c2d6-42b7-b9ff-f562d4ccce4e', 'up'  );
    $hrpg->updown('6a11dd4d-c2d6-42b7-b9ff-f562d4ccce4e', 'down');

Moves the habit in the direction specified. Returns a data structure of character status:

        exp   => 11,
        gp    => 15.5,
        hp    => 50,
        lv    => 2,
        delta => 1,



Convenience method. Equivalent to $hrpg-updown($task, 'up')>;



Convenience method. Equivalent to $hrpg-updown($task, 'down')>;


    $hrpg->_update($task, { attr => value });

This method should be considered experimental.

Updates the given task on the server (using the underlying PUT functionality in the API). Attributes are not checked for sanity, they're just directly converted into JSON.


    my @tasks = $hrpg->search_tasks($search_term, all => $bool);

    # Eg:
    my @tasks = $hrpg->search_tasks('floss');
    my @tasks = $hrpg->search_tasks('git', all => 1);

Search for tasks which match the provided search term. If the search term exactly matches a task ID, then the task ID is returned. Otherwise, returns a list of tasks which contain the search term in their names (the text field returned by the API). This list is in the same format as the as the "tasks" method call.

The search term is treated in a literal, case-insensitive fashion.

If the optional all parameter is set, then all tasks are returned. Otherwise only non-completed tasks are returned.

This is useful for providing a human-friendly way to refer to tasks. For example:

    # Search for a user-provided term
    my @tasks = $hrpg->search_tasks($term);
    # Increment task if found
    if (@tasks == 1) {
    else {
        say "Too few or too many tasks found.";


I'm sure there are plenty! Please view and/or record them at https://github.com/pjf/WebService-HabitRPG/issues .


The HabitRPG API spec.

The hrpg command-line client. It's freakin' awesome.


Paul Fenwick <pjf@cpan.org>


This software is copyright (c) 2013 by Paul Fenwick.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.