--- name: "sur" section: "1" platform: "linux" package: "subtle" version: "0.11.3224-xi-2.2+b8" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/sur" --- # sur(1) subtle user repository ## NAME **sur** - subtle user repository ## SYNOPSIS **sur** COMMAND *OPTIONS* ## DESCIPTION **sur** is the *subtle user repository* and a manager for sublets in a rubygems like fashion. The main goal of **sur** is to help the user managing sublets and to have a central point where new sublets can be found. Addionally **sur** has some capabilities to create and test sublets. ## COMMANDS - • **sur** *annotate* NAME \[-v VERSION\|-h\]\ Mark a sublet as to be reviewed - • **sur** *build* SPEC\ Create a sublet package - • **sur** *config* NAME\ Show available config settings of a sublet - • **sur** *fetch* NAME\ Download sublet to current directory - • **sur** *help*\ Show this help and exit - • **sur** *grabs* NAME\ Show available grabs provided by a sublet - • **sur** *info* NAME\ Show info about an installed sublet - • **sur** *install* NAME \[-R\|-t\|-v VERSION\|-h\]\ Install a sublet - • **sur** *list* \[-l\|-r\|-h\]\ List local/remote sublets - • **sur** *notes* NAME\ Show notes about a sublet - • **sur** *query* NAME \[-e\|-l\|-r\|-t\|-v VERSION\|-h\]\ Query for a sublet (e.g clock, clock -v 0.3) - • **sur** *reorder*\ Reorder installed sublets for loading order - • **sur** *server* \[-p PORT\|-h\]\ Serve sublets (default: http://localhost:4567) - • **sur** *submit* FILE\ Submit a sublet to SUR - • **sur** *template* FILE\ Create a new sublet template in current dir - • **sur** *test* NAME \[-C VALUE\|-h\]\ Test given sublets for syntax and functionality - • **sur** *uninstall* NAME \[-R\|-t\|-v VERSION\|-h\]\ Uninstall a sublet - • **sur** *unpack* NAME \[-t\|-v VERSION\|-h\]\ Unpack a sublet in current directory - • **sur** *update* \[-l\|-r\|-h\]\ Update local/remote sublet cache - • **sur** *upgrade* \[-R\|-y\|-h\]\ Upgrade all installed sublets - • **sur** *version*\ Show version info and exit - • **sur** *yank* NAME\ Delete sublet from server - ## OPTIONS - • **annotate** NAME \[-v VERSION\|-h\]\ **-v**, **--version** VERSION Annotate a specific version\ **-h**, **--help** Show this help and exit - • **fetch** NAME \[-t\|-v VERSION\|-h\]\ **-t**, **--tags** Include tags in search\ **-v**, **--version** VERSION Annotate a specific version\ **-h**, **--help** Show this help and exit - • **install** NAME \[-R\|-t\|-v VERSION\|-h\]\ **-R**, **--reload** Reload sublets after installing\ **-t**, **--tags** Include tags in search\ **-v**, **--version** VERSION Search for a specific version\ **-h**, **--help** Show this help and exit - • **list** \[-l\|-r\|-h\]\ **-l**, **--local** Select local repository (default)\ **-r**, **--remote** Select remote repository\ **-h**, **--help** Show this help and exit - • **query** NAME \[-e\|-l\|-r\|-t\|-v VERSION\|-h\]\ **-e**, **--regex** Use regex for query\ **-l**, **--local** Select local repository (default)\ **-r**, **--remote** Select remote repository\ **-t**, **--tags** Include tags in search\ **-v**, **--version** VERSION Search for a specific version\ **-h**, **--help** Show this help and exit - • **server** \[-p PORT\|-h\]\ **-p**, **--port** Select a specific port\ **-h**, **--help** Show this help and exit - • **test** NAME \[-C VALUE\|-h\]\ **-C**, **--config VALUE** Add config value (can be used multiple times)\ **-h**, **--help** Show this help and exit - • **unpack** NAME \[-t\|-v VERSION\|-h\]\ **-t**, **--tag** Search for a specific tag\ **-v**, **--version** VERSION Search for a specific version\ **-h**, **--help** Show this help and exit - • **uninstall** NAME \[-R\|-t\|-v VERSION\|-h\]\ **-R**, **--reload** Reload sublets after installing\ **-t**, **--tag** Search for a specific tag\ **-v**, **--version** VERSION Search for a specific version\ **-h**, **--help** Show this help and exit - • **update** \[-l\|-r\|-h\]\ **-l**, **--local** Select local repository (default)\ **-r**, **--remote** Select remote repository\ **-h**, **--help** Show this help and exit - • **upgrade** \[-R\|-y\|-h\]\ **-R**, **--reload** Reload sublets after upgrading\ **-y**, **--yes** Assume yes to questions\ **-h**, **--help** Show this help and exit - ## EXAMPLES ``` sur install clock sur query -r clock sur uninstall -v 0.1 clock ``` ## SPECIFICATION In order to create a sublet, you need to create a specifiction which basically contains some information about your sublet. Here is a list of known attributes: - • **name**\ Name of the sublet - **Example:** spec.name = "Sublet" - • **version**\ Version of the sublet - **Example:** spec.version = "0.1" - • **tags**\ List of tags to categorize the sublet - **Example:** spec.tags = \[ "Broken" \] - • **files**\ List of files in the sublet - **Example:** spec.files = \[ "sublet.rb" \] - • **icons**\ List of supplied icons - **Example:** spec.icons = \[ "icon.xbm" \] - • **description**\ Description of the sublet - **Example:** spec.description = "A shiny new sublet" - • **notes**\ Longer description of the sublet - **Example:** spec.notes = \<\ "format_string", :type => "string", :description => "Format of the clock (man date)" }, :def_value => "Default value" ``` - - }\ \] - • **grabs**\ Description of grabs - **Example:** spec.grabs = \[\ { - ``` :SubletTest => "Test grab", ``` - - }\ \] - • **required\_version**\ Required version of subtle - **Example:** spec.required\_version = "0.9.10" - • **add\_dependency(name, version)**\ Add a gem dependency - **Example**: spec.add\_dependency("a\_gem", "0.0") - If you use the **template** command **sur** will create an empty template with a spec file. ## BUGS Report bugs at http://subforge.org/projects/subtle/issues\ Homepage: http://subtle.subforge.org ## COPYRIGHT Copyright (c) Christoph Kappel *unexist@dorfelite.net* ## SEE ALSO [surserver(1)](/surserver/1.md), [subtle(1)](/subtle/1.md), [subtler(1)](/subtler/1.md), [subtlext(1)](/subtlext/1.md)