PowerShell Reddit API Wrapper Module
Project Site: https://github.com/markekraus/PSRAW
- Contributing to the PSRAW Project
- Using PSRAW
What Is Reddit?
Reddit is an American social news aggregation, web content rating, and discussion website. Reddit's registered community members can submit content such as text posts or direct links. Registered users can then vote submissions up or down that determines their position on the page. Submissions with the most up-votes appear on the front page or the top of a category. Content entries are organized by areas of interest called "subreddits". Subreddit topics include news, science, gaming, movies, music, books, fitness, food, image-sharing, and many others. The site prohibits harassment, and moderation requires substantial resources. (Source: Wikipedia)
What is PSRAW?
PSRAW is a Reddit API Wrapper module for the PowerShell scripting language. PSRAW allows for PowerShell command and object based access to Reddit's REST API. This allows for full access to all of Reddit's features including commenting, posting, messaging, and moderation provided by Reddit's API via PowerShell.
This module was created by Mark Kraus as new iteration of the ConnectReddit module. It is heavily inspired by the PRAW module for the python language and the PSMSGraph PowerShell module for Microsoft Graph API.
PSRAW 2.0 - PowerShell Core Compatibility Refactor
Many Many changes have been made to the module to make it compatible with PowerShell Core. The 2.0 release is a major version and many breaking changes will be introduced. Chief among them are the removal of the
Implicit grant flows. These grant flows required a GUI and GUI is not possible in PowerShell Core. In the future we will investigate bringing these grant flows back through CLI means. The current estimates for doing so would set this project back even further. We would rather provide the "Base" functionality release before tackling the additional grant flows. For most use cases for this module, the
Script grant flow should be sufficient.
With 2.0, PSRAW is now fully compatible with PowerShell Core and 6.0.0 (tested on 6.0.0-beta.5). However, it is still not cross-platform compatible and will only work on Windows. Currently, PowerShell Core on other platforms lacks support for
SecureStrings which PSRAW makes extensive use of for in-memory and at rest secrets (such as your Reddit Password). The PowerShell team is targeting 6.1 for inclusion/replacement of
SecureStrings on Linux. If there is enough demand or if the PowerShell team's goal post shifts too far into the future, we will investigate rolling our own cross-platform solution.
Besides default OAuth Tokens and
Connect-Reddit, this release will not add any additional functionality for users. Most of the changes are taking place "under the hood". The underlying class structures for upcoming functionality (such as retrieving comments) are being added but with no current functionality. If you begin using these classes in your projects please note that their shape and functionality may change dramatically in coming minor versions.
A new streamlined way of getting up and running with PSRAW has been added. The
Connect-Reddit command simplifies and consolidates the steps needed to begin accessing the API. You can either run it without any parameters to get interactive prompts to enter the required information, or you can pass the client credentials, user credentials, and redirect URI as parameters and be prompted for only what is missing.
Connect-Reddit will then use that information to create a default
RedditApplication and request a
Default OAuth Access Token
Having to manually pass the OAuth token around was repetitive and painful, especially when working in the console.
Update-RedditOAuthToken (with the
-SetDeafult parameter), and
Set-RedditDefaultOAuthToken can now all be used to set the default OAuth token for your session. To see the current Default OAuth Token you can use
Get-RedditDefaultOAuthToken. All commands that accept an
-AccessToken parameter ar now no longer mandatory and will use the Default Token if one is not provided. This allows you to continue using multiple identities via multiple
RedditOAuthToken objects while still making it easier to use PSRAW with a single identity.
For All news see the Project News page.
- Compatible with PowerShell Core on Windows (currently not cross-platform)
- In-memory and at-rest security of the Access Token, Refresh Token, Client Secret, and User Password.
- PowerShell v5 Classes for Reddit objects
- Easy OAuth authorization process
- No "Mystery DLL's" required. The entire OAuth authorization, token request, and token refresh process is written in native PowerShell
- Export and Import Access Tokens between sessions allowing you to authorize an application once and reuse the token until the refresh token has been revoked. Great for automation!
- No hassle Access Token Refreshing! Calls to
Invoke-RedditRequest(and all the functions that call it) automatically track the renewal needs for your Access Tokens and will automatically refresh them when needed.
- Built in Rate Limit monitoring, detection, and cooldown
- Rigorously tested code
- Thorough Online and In-Console Help Documentation
Contributing to the PSRAW Project
PSRAW is a community module made by the community for the community. However, the goal of this project is to maintain high quality best practice code and high quality documentation. We encourage community contributions but there are several considerations to be aware of before contributing. For more information see the Contributing to PSRAW document.
PSRAW is available on the PowerShell Gallery.
Save-Module -Name PSRAW -Path <path>
Install-Module -Name PSRAW
Documentation and Help
The online documentation for this module is available at https://psraw.readthedocs.io/
The in-console documentation can be access with
Get-Help, for example:
Get-Help Invoke-RedditRequest -Full Get-Help about_RedditOAuthToken
To see a quick example of how to use PSRAW see the Quickstart Example document.