{"id":15117076,"url":"https://github.com/Southclaws/sampctl","last_synced_at":"2025-09-27T22:32:09.856Z","repository":{"id":39821835,"uuid":"96704621","full_name":"Southclaws/sampctl","owner":"Southclaws","description":"The Swiss Army Knife of SA:MP - vital tools for any server owner or library maintainer.","archived":false,"fork":false,"pushed_at":"2025-09-08T10:34:05.000Z","size":143418,"stargazers_count":241,"open_issues_count":52,"forks_count":33,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-09-08T12:29:22.138Z","etag":null,"topics":["build-tool","command-line","ctl","dependency-manager","package-management","package-manager","pawn","sa-mp","sa-mp-development","sa-mp-server","server-tools"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Southclaws.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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-07-09T18:54:04.000Z","updated_at":"2025-08-16T06:44:14.000Z","dependencies_parsed_at":"2024-01-17T01:27:32.178Z","dependency_job_id":"bec75b07-0be5-4afe-88b8-f3d4b1f7c7ca","html_url":"https://github.com/Southclaws/sampctl","commit_stats":null,"previous_names":[],"tags_count":165,"template":false,"template_full_name":null,"purl":"pkg:github/Southclaws/sampctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Southclaws%2Fsampctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Southclaws%2Fsampctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Southclaws%2Fsampctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Southclaws%2Fsampctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Southclaws","download_url":"https://codeload.github.com/Southclaws/sampctl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Southclaws%2Fsampctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277302074,"owners_count":25795358,"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","status":"online","status_checked_at":"2025-09-27T02:00:08.978Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["build-tool","command-line","ctl","dependency-manager","package-management","package-manager","pawn","sa-mp","sa-mp-development","sa-mp-server","server-tools"],"created_at":"2024-09-26T01:45:49.564Z","updated_at":"2025-09-27T22:32:04.847Z","avatar_url":"https://github.com/Southclaws.png","language":"Go","funding_links":["https://ko-fi.com/southclaws"],"categories":["Go","Packages"],"sub_categories":["Software"],"readme":"# sampctl\n\n[![Build Status](https://travis-ci.org/Southclaws/sampctl.svg?branch=master)](https://travis-ci.org/Southclaws/sampctl)\n[![Go Report Card](https://goreportcard.com/badge/github.com/Southclaws/sampctl)](https://goreportcard.com/report/github.com/Southclaws/sampctl)\n[![Ko-Fi](https://shields.southcla.ws/badge/Ko--Fi-Buy%20Me%20a%20Coffee-brown.svg)](https://ko-fi.com/southclaws)\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2FSouthclaws%2Fsampctl.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2FSouthclaws%2Fsampctl?ref=badge_shield)\n\n![sampctl-logo](sampctl-wordmark.png)\n\nThe Swiss Army Knife of SA:MP - vital tools for any server owner or library\nmaintainer.\n\nsampctl is a **command-line development tool** for developing SA:MP **Pawn\nscripts**. It includes a **package manager**, a **build tool** and a\n**configuration manager**.\n\nIf that sentence meant nothing to you, don't worry! You'll probably find use in\nsampctl if you do anything related to the Pawn language. Below are some\nexplanations of what the terms in bold above mean.\n\n- **command-line development tool**: Whether you're a seasoned developer or just\n  a beginner, mastering the command-line on Windows and Unix systems is\n  absolutely necessary to speed up your workflow, take advantage of tools (like\n  this one) and just generally improve your knowledge of computing. If you've\n  never opened Cmd, PowerShell (Windows) or Terminal (Mac) then\n  [read this guide](https://www.learnenough.com/command-line-tutorial).\n- **Pawn scripts**: This includes gamemodes, filterscripts and libraries\n  (includes). sampctl introduces the concept of **packages** to the SA:MP and\n  Pawn world to make everyone's life easier.\n- **package manager**: This allows you to easily use and share packages, no more\n  downloading outdated `.inc` files from solidfiles...\n- **build tool**: Easily experiment with new versions of the compiler with a\n  simpler setup and automatic download feature.\n- **configuration manager**: server.cfg files can get messy and unmanageable,\n  sampctl can generate this file automatically from a much cleaner looking JSON\n  or YAML equivalent.\n\n[For a **quick-start** guide, click this link!](https://github.com/Southclaws/sampctl/wiki/Quick-Overview)\n\n## Features\n\nAs mentioned above, sampctl is a **command-line development tool** so it has no\ngraphical user interface. The videos below show sampctl being used with\n[Visual Studio Code](https://code.visualstudio.com) which is a light-weight text\neditor that works very well with sampctl to provide the perfect SA:MP/Pawn\ndevelopment environment.\n\n### Package Manager\n\nAlways have the libraries you need. Inspired by npm.\n\n![images/sampctl-package-ensure.gif](images/sampctl-package-ensure.gif)\n\n### Build/Run Tool\n\nUse on the command-line or integrate with any editor.\n\n![images/sampctl-package-build-vscode.gif](images/sampctl-package-build-vscode.gif)\n\nEasily write and run tests for libraries or quickly run arbitrary code. Utilise\nthe power of Docker to run on any platform!\n\n![images/sampctl-package-run-container.gif](images/sampctl-package-run-container.gif)\n\n### Developer Tools\n\nQuickly bootstrap new packages.\n\n![images/sampctl-package-init.gif](images/sampctl-package-init.gif)\n\n### SA:MP Server Configuration - no more `server.cfg`\n\nManage your server settings in JSON or YAML format\n\n![images/sampctl-server-init.gif](images/sampctl-server-init.gif)\n\n### Automatic Server Restart - no more dodgy bash scripts\n\nRun the server from `sampctl` and let it worry about restarting in case of\ncrashes.\n\n![images/sampctl-server-run.gif](images/sampctl-server-run.gif)\n\n### Automatic Server and Plugin Installer\n\nAutomatically download Windows/Linux server binaries and plugins when and where\nyou need them.\n\n![images/sampctl-server-ensure.gif](images/sampctl-server-ensure.gif)\n\n## Installation\n\nInstallation is simple and fast on all platforms so why not give sampctl a try?\n\n- [Linux (Debian/Ubuntu)](https://github.com/Southclaws/sampctl/wiki/Linux)\n- [Windows](https://github.com/Southclaws/sampctl/wiki/Windows)\n- [Mac](https://github.com/Southclaws/sampctl/wiki/Mac)\n\n## Usage\n\n[For a list of commands, click here.](https://github.com/Southclaws/sampctl#sampctl-1)\n\n[Or visit the Wiki site for documentation on each feature.](https://github.com/Southclaws/sampctl/wiki).\n\n---\n\n## Overview\n\nsampctl is designed for both development of gamemodes/libraries and management\nof live servers.\n\nBelow is a quick overview of the best features that will help _you_ develop\nfaster.\n\n### Package Management and Build Tool\n\nIf you've used platforms like NodeJS, Python, Go, Ruby, etc you know how useful\ntools like npm, pip, gem are.\n\nIt's about time Pawn had the same tool.\n\nsampctl provides a simple and intuitive way to _declare_ what includes your\nproject needs. After that you simply let sampctl take care of the downloading\nand building.\n\nIf you release scripts, you know it's awkward to test even simple code. You need\nto set up a server, compile the include into a gamemode, configure the server\nand run it.\n\nForget all that. Just make a\n[`pawn.json`/`pawn.yaml`](https://github.com/Southclaws/sampctl/wiki/Package-Definition-Reference)\nin your project directory with `sampctl package init` and use\n`sampctl package install` to get the includes you need:\n\n```json\n{\n  \"entry\": \"test.pwn\",\n  \"output\": \"test.amx\",\n  \"dependencies\": [\"pawn-lang/samp-stdlib\", \"Southclaws/formatex\"]\n}\n```\n\nWrite your quick test code:\n\n```pawn\n#include \u003ca_samp\u003e\n#include \u003cformatex\u003e\n\nmain() {\n    new str[128];\n    formatex(str, sizeof str, \"My favourite vehicle is: '%v'!\", 400); // should print \"Landstalker\"\n    print(str);\n}\n```\n\nBuild with `sampctl package build` and run it with `sampctl package run`!\n\n```bash\nsampctl package run\n\nServer Plugins\n--------------\n Loaded 0 plugins.\n\nStarted server on port: 7777, with maxplayers: 50 lanmode is OFF.\n\nFilterscripts\n---------------\n  Loaded 0 filterscripts.\n\nMy favourite vehicle is: 'Landstalker'!\n```\n\nYou get the compiler output and the server output without ever needing to:\n\n- visit sa-mp.com/download.php\n- unzip a server package\n- worry about Windows or Linux differences\n- set up the Pawn compiler with your favourite editor\n- make sure the Pawn compiler is reading the correct includes\n- download the formatex include\n\n[See documentation for more info.](https://github.com/Southclaws/sampctl/wiki/Packages)\n\n### Server Configuration and Automatic Plugin Download\n\nUse JSON or YAML to write your server config:\n\n```json\n{\n  \"gamemodes\": [\"rivershell\"],\n  \"plugins\": [\"maddinat0r/sscanf\"],\n  \"rcon_password\": \"test\",\n  \"port\": 8080\n}\n```\n\nIt compiles to this:\n\n```conf\ngamemode0 rivershell\nplugins sscanf.so\nrcon_password test\nport 8080\n(... and the rest of the settings which have default values)\n```\n\nWhat also happens here is `maddinat0r/sscanf` tells sampctl to automatically get\nthe latest sscanf plugin and place the `.so` or `.dll` file into the `plugins/`\ndirectory.\n\n[See documentation for more info.](https://github.com/Southclaws/sampctl/wiki/Runtime-Configuration-Reference)\n\n---\n\n# `sampctl`\n\n1.10.0 - Southclaws \u003chello@southcla.ws\u003e\n\nThe Swiss Army Knife of SA:MP - vital tools for any server owner or library maintainer.\n\n## Commands (6)\n\n### `sampctl`\n\nUsage: `sampctl \u003csubcommand\u003e`\n\nFor managing servers and runtime configurations.\n\n#### Subcommands (4)\n\n### `sampctl init`\n\nUsage: `sampctl init`\n\nBootstrap a new SA:MP server and generates a `samp.json`/`samp.yaml` configuration based on user input. If `gamemodes`, `filterscripts` or `plugins` directories are present, you will be prompted to select relevant files.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--version value`: the SA:MP server version to use (default: \"0.3.7\")\n- `--dir value`: working directory for the server - by default, uses the current directory (default: \".\")\n\n### `sampctl download`\n\nUsage: `sampctl download`\n\nDownloads the files necessary to run a SA:MP server to the current directory (unless `--dir` specified). Will download the latest stable (non RC) server version unless `--version` is specified.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--version value`: the SA:MP server version to use (default: \"0.3.7\")\n- `--dir value`: working directory for the server - by default, uses the current directory (default: \".\")\n\n### `sampctl ensure`\n\nUsage: `sampctl ensure`\n\nEnsures the server environment is representative of the configuration specified in `samp.json`/`samp.yaml` - downloads server binaries and plugin files if necessary and generates a `server.cfg` file.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--dir value`: working directory for the server - by default, uses the current directory (default: \".\")\n- `--noCache --forceEnsure`: forces download of plugins if --forceEnsure is set\n\n### `sampctl run`\n\nUsage: `sampctl run`\n\nGenerates a `server.cfg` file based on the configuration inside `samp.json`/`samp.yaml` then executes the server process and automatically restarts it on crashes.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--dir value`: working directory for the server - by default, uses the current directory (default: \".\")\n- `--container`: starts the server as a Linux container instead of running it in the current directory\n- `--mountCache --container`: if --container is set, mounts the local cache directory inside the container\n- `--noCache`: forces download of plugins\n\n---\n\n### `sampctl package`\n\nUsage: `sampctl package \u003csubcommand\u003e`\n\nFor managing Pawn packages such as gamemodes and libraries.\n\n#### Subcommands (9)\n\n### `sampctl package init`\n\nUsage: `sampctl package init`\n\nHelper tool to bootstrap a new package or turn an existing project into a package.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--dir value`: working directory for the project - by default, uses the current directory (default: \".\")\n\n### `sampctl package ensure`\n\nUsage: `sampctl package ensure`\n\nEnsures dependencies are up to date based on the `dependencies` field in `pawn.json`/`pawn.yaml`.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--dir value`: working directory for the project - by default, uses the current directory (default: \".\")\n- `--update`: update cached dependencies to latest version\n\n### `sampctl package install`\n\nUsage: `sampctl package install [package definition]`\n\nInstalls a new package by adding it to the `dependencies` field in `pawn.json`/`pawn.yaml` and downloads the contents.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--dir value`: working directory for the project - by default, uses the current directory (default: \".\")\n- `--dev`: for specifying dependencies only necessary for development or testing of the package\n\n### `sampctl package uninstall`\n\nUsage: `sampctl package uninstall [package definition]`\n\nUninstalls package by removing it from the `dependencies` field in `pawn.json`/`pawn.yaml` and deletes the contents.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--dir value`: working directory for the project - by default, uses the current directory (default: \".\")\n- `--dev`: for specifying development dependencies\n\n### `sampctl package release`\n\nUsage: `sampctl package release`\n\nCreates a release version and tags the repository with the next version number, creates a GitHub release with archived package files.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--dir value`: working directory for the project - by default, uses the current directory (default: \".\")\n\n### `sampctl package get`\n\nUsage: `sampctl package get [package definition] (target path)`\n\nClones a GitHub package to either a directory named after the repo or, if the cwd is empty, the cwd and then ensures the package.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n\n### `sampctl package build`\n\nUsage: `sampctl package build [build name]`\n\nBuilds a package defined by a `pawn.json`/`pawn.yaml` file.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--dir value`: working directory for the project - by default, uses the current directory (default: \".\")\n- `--forceEnsure`: forces dependency ensure before build\n- `--dryRun`: does not run the build but outputs the command necessary to do so\n- `--watch`: keeps sampctl running and triggers builds whenever source files change\n- `--buildFile value`: declares a file to store the incrementing build number for easy versioning\n- `--relativePaths`: force compiler output to use relative paths instead of absolute\n\n### `sampctl package run`\n\nUsage: `sampctl package run`\n\nCompiles and runs a package defined by a `pawn.json`/`pawn.yaml` file.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--dir value`: working directory for the server - by default, uses the current directory (default: \".\")\n- `--container`: starts the server as a Linux container instead of running it in the current directory\n- `--build --forceBuild`: build configuration to use if --forceBuild is set\n- `--forceBuild`: forces a build to run before executing the server\n- `--forceEnsure --forceBuild`: forces dependency ensure before build if --forceBuild is set\n- `--noCache --forceEnsure`: forces download of plugins if --forceEnsure is set\n- `--watch`: keeps sampctl running and triggers builds whenever source files change\n- `--buildFile value`: declares a file to store the incrementing build number for easy versioning\n- `--relativePaths`: force compiler output to use relative paths instead of absolute\n\n### `sampctl package template`\n\nUsage: `sampctl package template \u003csubcommand\u003e`\n\nProvides commands for package templates\n\n#### Subcommands (3)\n\n### `sampctl package template make`\n\nUsage: `sampctl package template make [name]`\n\nCreates a template package from the current directory if it is a package.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--dir value`: working directory for the package - by default, uses the current directory (default: \".\")\n- `--update`: update cached dependencies to latest version\n\n### `sampctl package template build`\n\nUsage: `sampctl package template build [template] [filename]`\n\nBuilds the specified file in the context of the given template.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n\n### `sampctl package template run`\n\nUsage: `sampctl package template run [template] [filename]`\n\nBuilds and runs the specified file in the context of the given template.\n\n#### Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--version value`: the SA:MP server version to use (default: \"0.3.7\")\n- `--mode value`: runtime mode, one of: server, main, y_testing (default: \"main\")\n\n---\n\n### `sampctl version`\n\nShow version number - this is also the version of the container image that will be used for `--container` runtimes.\n\n---\n\n### `sampctl completion`\n\noutput bash autocomplete code\n\n---\n\n### `sampctl docs`\n\nUsage: `sampctl docs \u003e documentation.md`\n\nGenerate documentation in markdown format and print to standard out.\n\n---\n\n### `sampctl help`\n\nUsage: `Shows a list of commands or help for one command`\n\n---\n\n## Global Flags\n\n- `--verbose`: output all detailed information - useful for debugging\n- `--platform windows`: manually specify the target platform for downloaded binaries to either windows, `linux` or `darwin`.\n- `--bare`: skip all pre-run configuration\n- `--help, -h`: show help\n- `--appVersion, -V`: sampctl version\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSouthclaws%2Fsampctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSouthclaws%2Fsampctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSouthclaws%2Fsampctl/lists"}