{"id":13688385,"url":"https://github.com/papertrail/papertrail-cli","last_synced_at":"2025-05-01T19:30:54.870Z","repository":{"id":50907584,"uuid":"1344271","full_name":"papertrail/papertrail-cli","owner":"papertrail","description":"Command-line client for Papertrail hosted syslog \u0026 app log management service","archived":false,"fork":false,"pushed_at":"2023-12-15T19:23:15.000Z","size":212,"stargazers_count":428,"open_issues_count":31,"forks_count":46,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-04-13T14:42:45.019Z","etag":null,"topics":["papertrail","ruby","rubygems"],"latest_commit_sha":null,"homepage":"http://papertrailapp.com/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/papertrail.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2011-02-08T23:58:41.000Z","updated_at":"2025-03-30T18:24:32.000Z","dependencies_parsed_at":"2024-01-17T06:16:53.063Z","dependency_job_id":null,"html_url":"https://github.com/papertrail/papertrail-cli","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papertrail%2Fpapertrail-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papertrail%2Fpapertrail-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papertrail%2Fpapertrail-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papertrail%2Fpapertrail-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/papertrail","download_url":"https://codeload.github.com/papertrail/papertrail-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251932620,"owners_count":21667183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["papertrail","ruby","rubygems"],"created_at":"2024-08-02T15:01:12.717Z","updated_at":"2025-05-01T19:30:54.502Z","avatar_url":"https://github.com/papertrail.png","language":"Ruby","readme":"# papertrail command-line tail \u0026 search client for Papertrail log management service\n\n[![Build Status](https://travis-ci.org/papertrail/papertrail-cli.svg?branch=master)](https://travis-ci.org/papertrail/papertrail-cli)\n\nSmall standalone [binary] to retrieve, search, and tail recent app\nserver log and system syslog messages from [Papertrail].\n\nSupports optional Boolean search queries and polling for new events\n(like \"tail -f\"). Example:\n\n    $ papertrail -f \"(www OR db) (nginx OR pgsql) -accepted\"\n\nOutput is line-buffered so it can be fed into a pipe, like for grep.\nANSI color codes are rendered in color on suitable terminals; see below for\nadditional colorization options.\n\nThe [Connection] class can be used by other apps to perform one-off\nAPI searches or follow (tail) events matching a given query. Interface\nmay change.\n\nAlso includes `papertrail-add-system`, `papertrail-remove-system`,\n`papertrail-add-group`, and `papertrail-join-group` binaries, which\ninvoke the corresponding Papertrail [HTTP API] call.\n\n\n## Quick Start\n\n    $ [sudo] gem install papertrail\n    $ echo \"token: 123456789012345678901234567890ab\" \u003e ~/.papertrail.yml\n    $ papertrail\n\nRetrieve the token from Papertrail [User Profile].\n\nThe API token can also be passed in the `PAPERTRAIL_API_TOKEN`\nenvironment variable instead of a configuration file. Example:\n\n    $ export PAPERTRAIL_API_TOKEN='abc123'\n    $ papertrail\n\n\n## Installation\n\nInstall the gem (details on [RubyGems]), which includes a binary called\n\"papertrail\":\n\n    $ [sudo] gem install papertrail\n\n\n## Configuration\n\nCreate ~/.papertrail.yml containing your API token, or specify the\npath to that file with -c. Example (from\nexamples/papertrail.yml.example):\n\n    token: 123456789012345678901234567890ab\n\nRetrieve token from Papertrail [User Profile]. For compatibility with\nolder config files, `username` and `password` keys are also supported.\n\nYou may want to alias \"pt\" to \"papertrail\", like:\n\n    echo \"alias pt=papertrail\" \u003e\u003e ~/.bashrc\n\n## Usage \u0026 Examples\n\n    $ papertrail --help\n    papertrail - command-line tail and search for Papertrail log management service\n        -h, --help                       Show usage\n        -f, --follow                     Continue running and printing new events (off)\n            --min-time MIN               Earliest time to search from\n            --max-time MAX               Latest time to search from\n        -d, --delay SECONDS              Delay between refresh (2)\n        -c, --configfile PATH            Path to config (~/.papertrail.yml)\n        -g, --group GROUP                Group to search\n        -S, --search SEARCH              Saved search to search\n        -s, --system SYSTEM              System to search\n        -j, --json                       Output raw JSON data (off)\n            --color [program|system|all|off]\n                                         Attribute(s) to colorize based on (program)\n            --force-color                Force use of ANSI color characters even on non-tty outputs (off)\n        -V, --version                    Display the version and exit\n\n      Usage:\n        papertrail [-f] [--min-time time] [--max-time time] [-g group] [-S search]\n          [-s system] [-d seconds] [-c papertrail.yml] [-j] [--color attributes]\n          [--force-color] [--] [query]\n\n      Examples:\n        papertrail -f\n        papertrail something\n        papertrail 1.2.3 Failure\n        papertrail -s ns1 \"connection refused\"\n        papertrail -f \"(www OR db) (nginx OR pgsql) -accepted\"\n        papertrail -f -g Production --color all \"(nginx OR pgsql) -accepted\"\n        papertrail --min-time 'yesterday at noon' --max-time 'today at 4am' -g Production\n        papertrail -- -redis\n\n      More: https://github.com/papertrail/papertrail-cli\n            https://papertrailapp.com/\n\n\n### Count, pivot, and summarize\n\nTo count the number of matches, pipe to `wc -l`. For example, count how\nmany logs contained `Failure` in the last minute:\n\n    $ papertrail --min-time '1 minute ago' Failure | wc -l\n    42\n\nOutput only the program/file name (which is output as field 5):\n\n    $ papertrail --min-time '1 minute ago' | cut -f 5 -d ' '\n    passenger.log:\n    sshd:\n    app/web.2:\n\nCount by source/system name (field 4):\n\n    $ papertrail --min-time '1 minute ago' | cut -f 4 -d ' ' | sort | uniq -c\n      98 www42\n      39 acmedb-core01\n      2 fastly\n\nFor sum, mean, and statistics, see\n[datamash](http://www.gnu.org/software/datamash/) and [one-liners](https://www.gnu.org/software/datamash/alternatives/).\n\n### Colors\n\nANSI color codes are retained, so log messages which are already colorized\nwill automatically render in color on ANSI-capable terminals.\n\nBy default, the CLI will colorize the non-body portion of each log message\nbased on the value of the program attribute. 5 colors are available, so colors\nmay not be unique. When the sending system name is more important than the\nprogram, use `--color=system` to colorize based on its value. Use `--color=all`\nto colorize based on both together.\n\nFor content-based colorization, pipe through [lnav]. Install `lnav` from your\npreferred package repository, such as `brew install lnav` or\n`apt-get install lnav`, then:\n\n    $ papertrail -f | lnav\n    $ papertrail --min-time \"1 hour ago\" error | lnav\n\n### Redirecting output\n\nSince output is line-buffered, pipes and output redirection will automatically\nwork:\n\n    $ papertrail | less\n    $ papertrail --min-time '2016-01-15 10:00:00' \u003e logs.txt\n\nIf you frequently pipe output to a certain command, create a function which\naccepts optional arguments, invokes `papertrail` with any arguments, and pipes\noutput to that command. For example, this `pt` function will pipe to `lnav`:\n\n    $ function pt() { papertrail -f -d 5 $* | lnav; }\n\nAdd the `function` line to your `~/.bashrc`. It can be invoked with search\nparameters:\n\n    $ pt 1.2.3 Failure\n\n### UTF-8 (non-English searches)\n\nWhen searching in a language other than English, if you get no matches, you\nmay need to explicitly tell Ruby to use UTF-8. Ruby 1.9 honors the `LANG`\nshell environment variable, and your shell may not set it to `UTF-8`.\n\nTo test, try:\n\n    ruby -E:UTF-8 -S papertrail your_search\n\nIf that works, add `-E:UTF-8` to the `RUBYOPT` variable to set the encoding\nat invocation. For example, to persist that in a `.bashrc`:\n\n    export RUBYOPT=\"-E:UTF-8\"\n\n### Negation-only queries\n\nUnix shells handle arguments beginning with hyphens (`-`) differently\n([why](http://unix.stackexchange.com/questions/11376/what-does-double-dash-mean)).\nUsually this is moot because most searches start with a positive match.\nTo search only for log messages without a given string, use `--`. For\nexample, to search for `-whatever`, run:\n\n    papertrail -- -whatever\n\n### Time zones\n\nTimes are interpreted in the client itself, which means it uses the time\nzone that your local PC is set to. Log timestamps are also output in the\nsame local PC time zone.\n\nWhen providing absolute times, append `UTC` to provide the input time in\nUTC. For example, regardless of the local PC time zone, this will show\nmessages beginning from 1 PM UTC:\n\n    papertrail --min-time \"2014-04-27 13:00:00 UTC\"\n\nOutput timestamps will still be in the local PC time zone.\n\n### Quoted phrases\n\nBecause the Unix shell parses and strips one set of quotes around a\nphrase, to search for a phrase, wrap the string in both single-quotes\nand double-quotes. For example:\n\n    papertrail -f '\"Connection reset by peer\"'\n\nUse one set of double-quotes and one set of single-quotes. The order\ndoes not matter as long as the pairs are consistent.\n\nNote that many phrases are unique enough that searching for the\nwords yields the same results as searching for the quoted phrase. As a\nresult, quoting strings twice is often not actually necessary. For\nexample, these two searches are likely to yield the same log messages,\neven though one is for 4 words (AND) while the other is for a phrase:\n\n    papertrail -f Connection reset by peer\n    papertrail -f '\"Connection reset by peer\"'\n\n### Multiple API tokens\n\nTo use multiple API tokens (such as for separate home and work Papertrail\naccounts), create a `.papertrail.yml` configuration file in each project's\nworking directory and invoke the CLI in that directory. The CLI checks for\n`.papertrail.yml` in the current working directory prior to using\n`~/.papertrail.yml`.\n\nAlternatively, use shell aliases with different `-c` paths. For example:\n\n    echo \"alias pt1='papertrail -c /path/to/papertrail-home.yml'\" \u003e\u003e ~/.bashrc\n    echo \"alias pt2='papertrail -c /path/to/papertrail-work.yml'\" \u003e\u003e ~/.bashrc\n\n\n## Add/Remove Systems, Create Group, Join Group\n\nIn addition to tail and search with the `papertrail` binary, the gem includes\n4 other binaries which wrap other parts of Papertrail's [HTTP API] to explicitly\nadd or remove a system, to create a new group, and to join a system to a group.\n\nIn most cases, configuration is automatic and these are not not necessary.\n\nTo see usage, run any of these commands with `--help`: `papertrail-add-system`,\n`papertrail-remove-system`, `papertrail-add-group`, `papertrail-join-group`.\n\n\n## Releasing\n\n### Build\n\n1. Bump `VERSION` in `lib/papertrail.rb`\n2. Build the new gem: `$ rake build`\n\n### Install \u0026 Test\n\n1. Install built gem: `$ gem install pkg/papertrail-0.9.17.gem`\n2. Check version in rubygems: `$ gem list papertrail`\n4. Verify installed version matches: `$ which papertrail \u0026\u0026 papertrail --version`\n4. Test: `$ papertrail test search string`\n5. Uninstall local gem `$ gem uninstall papertrail`\n\n### Release\n\n1. Release: `$ rake release`\n2. Check latest published version: `$ gem list --versions --remote papertrail`\n3. Install release version: `$ gem install papertrail`\n4. Verify installed version matches: `$ which papertrail \u0026\u0026 papertrail --version`\n5. Test: `$ papertrail test search string`\n6. Party! :tada: :balloon: :confetti_ball:\n\n\n## Contribute\n\nTesting:\n\nRun all the tests with `rake`\n\nTo run the tests when files save, run `bundle exec guard` (requires ruby version \u003e= 2.2.5).\n\nBug report:\n\n1. See whether the issue has already been reported:\n   http://github.com/papertrail/papertrail-cli/issues/\n2. If you don't find one, create an issue with a repro case.\n\nEnhancement or fix:\n\n1. Fork the project:\n   http://github.com/papertrail/papertrail-cli\n2. Make your changes with tests.\n3. Commit the changes without changing the Rakefile or other files unrelated\nto your enhancement.\n4. Send a pull request.\n\n[binary]: https://github.com/papertrail/papertrail-cli/blob/master/bin/papertrail\n[Papertrail]: http://papertrailapp.com/\n[Connection]: https://github.com/papertrail/papertrail-cli/blob/master/lib/papertrail/connection.rb\n[HTTP API]: http://help.papertrailapp.com/kb/how-it-works/http-api\n[User Profile]: https://papertrailapp.com/account/profile\n[RubyGems]: https://rubygems.org/gems/papertrail-cli\n[lnav]: http://lnav.org/\n[escape characters]: http://en.wikipedia.org/wiki/ANSI_escape_code#Colors\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapertrail%2Fpapertrail-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpapertrail%2Fpapertrail-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapertrail%2Fpapertrail-cli/lists"}