{"id":25781677,"url":"https://github.com/kira-nt/outline-cli","last_synced_at":"2025-04-06T04:08:16.494Z","repository":{"id":247297791,"uuid":"783803072","full_name":"Kira-NT/outline-cli","owner":"Kira-NT","description":"🌐 The Free and Open Internet™ right in your terminal.","archived":false,"fork":false,"pushed_at":"2025-04-02T15:23:16.000Z","size":128,"stargazers_count":117,"open_issues_count":0,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-06T04:07:42.155Z","etag":null,"topics":["cli","linux","outline","outline-vpn","shadowsocks"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/Kira-NT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-08T15:47:08.000Z","updated_at":"2025-04-05T13:22:14.000Z","dependencies_parsed_at":"2024-12-25T11:13:45.261Z","dependency_job_id":"9c7f8f4c-ab12-413e-a369-df7a91126da8","html_url":"https://github.com/Kira-NT/outline-cli","commit_stats":{"total_commits":50,"total_committers":2,"mean_commits":25.0,"dds":"0.020000000000000018","last_synced_commit":"52f2b04755b03b9bdb8edb645726f61f4b1bf9fa"},"previous_names":["kir-antipov/outline-cli","kira-nt/outline-cli"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kira-NT%2Foutline-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kira-NT%2Foutline-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kira-NT%2Foutline-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kira-NT%2Foutline-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kira-NT","download_url":"https://codeload.github.com/Kira-NT/outline-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247430868,"owners_count":20937874,"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":["cli","linux","outline","outline-vpn","shadowsocks"],"created_at":"2025-02-27T07:14:20.063Z","updated_at":"2025-04-06T04:08:16.346Z","avatar_url":"https://github.com/Kira-NT.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Outline CLI\n\n[![GitHub CI Status](https://img.shields.io/github/actions/workflow/status/Kira-NT/outline-cli/ci.yml?logo=github)](https://github.com/Kira-NT/outline-cli/actions/workflows/ci.yml)\n[![Version](https://img.shields.io/github/v/release/Kira-NT/outline-cli?sort=date\u0026label=version)](https://github.com/Kira-NT/outline-cli/releases/latest)\n[![License](https://img.shields.io/github/license/Kira-NT/outline-cli?cacheSeconds=36000)](LICENSE.md)\n\n\u003cimg alt=\"Outline CLI Icon\" src=\"media/icon.png\" width=\"128\"\u003e\n\n[Outline](https://getoutline.org/), developed by [Jigsaw](https://jigsaw.google.com/), is a great project aimed at simplifying the task of creating self-hosted VPN servers down to a matter of seconds. However, while the server deployment with Outline is commendable, its client-side experience falls short. Currently, the primary method of connecting to an [Outline server](https://github.com/Jigsaw-Code/outline-server/) is via the [Outline Client](https://github.com/Jigsaw-Code/outline-apps/) - an Electron *(or Cordova for mobile devices)* app - which unfortunately presents lots of issues across different platforms. It is somewhat buggy on Windows, notably unreliable on macOS, and entirely non-functional on Linux *(at least if Linux means more than just Ubuntu to you)*.\n\nFortunately, at least for Linux users, there's an alternative - a [CLI solution](https://github.com/Jigsaw-Code/outline-sdk/tree/main/x/examples/outline-cli/) hidden within the \"experimental\" section of the [outline-sdk](https://github.com/Jigsaw-Code/outline-sdk/) repo, which only supports Linux at the moment of writing. Despite its minimalistic design, the CLI performs its sole function - establishing a connection to a selected server and rerouting all traffic through it - quite efficiently and reliably. However, it may not be very user-friendly to manually launch/restart it, manage your access keys, and forcibly stop it when you wish to disconnect from the VPN server, and so on. This is where this project comes in.\n\nThis project, essentially a wrapper over the official [outline-cli](https://github.com/Jigsaw-Code/outline-sdk/tree/main/x/examples/outline-cli/) provided by [Jigsaw](https://github.com/Jigsaw-Code/), aims to make its usage easier. Comprised of just a few shell scripts, it enhances the default experience into a near-perfect one - unachievable by a buggy Electron app ;)\n\n----\n\n## Features\n\nObviously, the official CLI provides you with the ability to connect to servers deployed by the Outline Manager, or to any Shadowsocks server, for that matter. Here is what this project offers on top of that:\n\n- Access key management\n- [`ssconf://`](https://www.reddit.com/r/outlinevpn/wiki/index/dynamic_access_keys/) support\n- Option to specify a custom DNS resolver instead of the hardcoded one\n- Ability to connect to devices on your local network while the VPN is active\n- Automatic reconnection to the VPN server upon reboot/network status change *(requires `NetworkManager`)*\n- Easy integration with other tools, thanks to the highly scriptable nature of this project\n\n----\n\n## Installation\n\nThe installation process is quite straightforward: just clone this repo and run the `install.sh` script.\n\n```sh\ngit clone https://github.com/Kira-NT/outline-cli\ncd outline-cli\nsudo ./install.sh -y\n```\n\nAlternatively, for `curl $URL | sudo bash` enjoyers, the same result can be achieved with the following one-liner:\n\n```sh\ncurl -Ls https://github.com/Kira-NT/outline-cli/blob/master/install.sh?raw=true | sudo bash -s -- -y\n```\n\nThis will:\n\n1) Install any missing dependencies: `git`, `tar`, `jq`, `curl` or `wget`, `gcc` or `clang`\n2) Build and install the official [`outline-cli`](https://github.com/Jigsaw-Code/outline-sdk/tree/main/x/examples/outline-cli/)\n   1) Clone [`Jigsaw-Code/outline-sdk`](https://github.com/Jigsaw-Code/outline-sdk/)\n   2) Apply a patch that allows you to specify a custom DNS resolver instead of the hardcoded one\n   3) Download the latest version of Go *(locally, not globally)*\n   4) Build the app\n   5) Copy the resulting binary to `/usr/local/bin/__vpn_connect`\n   6) Clean up\n3) Copy the `__vpn_manager` script to `/usr/local/bin/__vpn_manager`\n4) Create a symlink for `__vpn_manager`, enabling you to call it using the shorthand `vpn`\n5) Create a `polkit-1` policy, enabling you to call `__vpn_manager` from scripts\n6) Copy the `vpn-manager-refresh` script to `/etc/NetworkManager/dispatcher.d/vpn-manager-refresh`, ensuring it executes each time your network connection status changes\n\nIf you wish to configure the process described above, you can run the installation script without the `-y` flag, allowing you to guide it and adjust the results according to your preferences.\n\n----\n\n## Usage\n\n```\nUsage: vpn \u003ccommand\u003e [\u003cargs\u003e] [\u003coptions\u003e]\n\nManage Shadowsocks server connections and related access keys.\n\nExamples:\n  sudo vpn add \"ss://...\" \"Geneva\"\n  sudo vpn connect geneva\n  sudo vpn disconnect\n\nCommands:\n  add \u003ckey\u003e [\u003cname\u003e]        Add a new access key\n  remove \u003cname | index\u003e     Remove the designated access key\n  list [-f \u003cformat\u003e]        List all stored access keys\n  connect [\u003cname | index\u003e]  Connect to a server\n  disconnect [-s]           Disconnect from the current server\n  toggle                    Toggle the current connection\n  status                    Return the current connection status\n\nOptions:\n  -h, --help                Display this help text and exit\n  -v, --version             Display version information and exit\n  -q, --quiet               Suppress all normal output\n  -n, --notify              Display a notification\n  -s, --suspend             Suspend the current connection;\n                            It will be re-established later\n  -f, --format \u003cformat\u003e     Print a key according to the \u003cformat\u003e;\n                            The formats are: %name%, %ip%, %index%\n```\n\nFirst and foremost, akin to the GUI app, you must add an access key. For example:\n\n```sh\nsudo vpn add \"ss://YFhvLUKmUBJwEsSfL65ShwAOzuLDNN0HTBh9rCb2yhIJdrMXBhgP1DXBm4y7@42.42.42.42:52683/?outline=1\" \"Geneva\"\n```\n\nYou can list all stored access keys using the `sudo vpn list` command:\n\n```\n1  Geneva  42.42.42.42:52683\n```\n\nOnce done, you're all set! Use:\n\n```sh\nsudo vpn connect \"Geneva\"\n```\n\nor one of these alternatives:\n\n```sh\n# The access key name is case-insensitive.\nsudo vpn connect geneva\n\n# You can also use the saved access key's ID\n# (i.e., its ordinal number from the `list` output).\nsudo vpn connect 1\n\n# You can also omit the name/ID entirely.\n# This will connect you to the last server you connected to.\nsudo vpn connect\n```\n\nto connect to the desired VPN server.\n\nWhenever you wish to disconnect from the current server, simply use:\n\n```sh\nsudo vpn disconnect\n```\n\nAnd that about covers the most essential functionalities you'll need.\n\n----\n\n## Keyboard Shortcuts\n\nWhile this project doesn't provide a built-in solution for automatically creating keyboard shortcuts *(since everyone does it differently, and there's no point in even attempting to support every DE/WM/key remapping tool in existence)*, it is designed to be easily integrated with other tools and is highly scriptable.\n\nHere’s a table with some common actions you might want to perform and the commands that achieve the desired results:\n\n| Description                                             | Command                                             |\n|:--------------------------------------------------------|:----------------------------------------------------|\n| Toggle the current connection                           | `pkexec /usr/local/bin/__vpn_manager toggle -n`     |\n| Disconnect from the current server                      | `pkexec /usr/local/bin/__vpn_manager disconnect -n` |\n| Connect to the server you were last connected to        | `pkexec /usr/local/bin/__vpn_manager connect -n`    |\n| Show the current connection status                      | `pkexec /usr/local/bin/__vpn_manager status -n`     |\n| Connect to a server using the 1\u003csup\u003est\u003c/sup\u003e access key | `pkexec /usr/local/bin/__vpn_manager connect 1 -n`  |\n| Connect to a server using the 2\u003csup\u003end\u003c/sup\u003e access key | `pkexec /usr/local/bin/__vpn_manager connect 2 -n`  |\n| Connect to a server using the 3\u003csup\u003erd\u003c/sup\u003e access key | `pkexec /usr/local/bin/__vpn_manager connect 3 -n`  |\n| Connect to a server using the 4\u003csup\u003eth\u003c/sup\u003e access key | `pkexec /usr/local/bin/__vpn_manager connect 4 -n`  |\n| Connect to a server using the 5\u003csup\u003eth\u003c/sup\u003e access key | `pkexec /usr/local/bin/__vpn_manager connect 5 -n`  |\n| Connect to a server using the 6\u003csup\u003eth\u003c/sup\u003e access key | `pkexec /usr/local/bin/__vpn_manager connect 6 -n`  |\n| Connect to a server using the 7\u003csup\u003eth\u003c/sup\u003e access key | `pkexec /usr/local/bin/__vpn_manager connect 7 -n`  |\n| Connect to a server using the 8\u003csup\u003eth\u003c/sup\u003e access key | `pkexec /usr/local/bin/__vpn_manager connect 8 -n`  |\n| Connect to a server using the 9\u003csup\u003eth\u003c/sup\u003e access key | `pkexec /usr/local/bin/__vpn_manager connect 9 -n`  |\n\nWith this, you can easily configure keyboard shortcuts either directly via the keyboard settings provided by your DE/WM *(e.g., KDE, GNOME, etc.)*, or via a key remapping tool of your choice.\n\nFor example, I use [`keyd`](https://github.com/rvaiya/keyd/) - a very nice, modular, and efficient key remapping daemon. You can check my config, which implements all the shortcuts mentioned above, here: [`src/etc/keyd/vpn-manager.conf`](src/etc/keyd/vpn-manager.conf).\n\n----\n\n## Custom DNS Resolver\n\nThe Outline Client hardcodes its preferred DNS resolver. This has already caused many problems for numerous users in the past and will undoubtedly cause even more issues in the future.\n\nWhile striving for the perfect solution is understandable, \"perfect\" can often be the enemy of \"good.\" This is precisely what we see here, as after all these years, there is still no option to override these hardcoded values. Hence, this project proposes a simple eight-line patch that allows you to supply a DNS resolver of your choice to the Outline Client.\n\nIf you followed the standard installation script, you can specify the DNS resolver you prefer directly in your access key via the new `dns` URL parameter, as demonstrated below:\n\n```diff\n- ss://.../?outline=1\n+ ss://.../?outline=1\u0026dns=1.1.1.1\n```\n\n----\n\n## Legal Notice\n\nThis project is an independent work and is not affiliated, endorsed, authorized, or sponsored by Jigsaw LLC or any of its subsidiaries or affiliates. Outline and the Outline logo are trademarks and/or registered trademarks of Jigsaw LLC in the U.S. and/or other countries. All rights reserved to their respective owners.\n\nThe purpose of this project is purely educational and non-commercial. The code and information found within this project are for educational use only and are not intended for any kind of commercial use.\n\nUse this software at your own risk. The creators cannot be held responsible for any misuse or damages caused by this software.\n\nThis notice serves as a disclaimer. Any violations of Jigsaw's policies or trademarks are not intentional.\n\n----\n\n## License\n\nLicensed under the terms of the [MIT License](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkira-nt%2Foutline-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkira-nt%2Foutline-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkira-nt%2Foutline-cli/lists"}