Files
skillshare/website/docs/getting-started/quick-reference.md
T
Willie 5d269e8e4c feat(push): add --pull for two-way sync in one command (#354)
* feat(push): add --pull for two-way sync in one command

Users editing skills on several machines have to remember push on one and pull on the other, and a push from a machine that is behind fails until they pull first. push --pull commits local changes, merges the remote with the same merge semantics pull uses, pushes, and syncs the git root scope.

A conflict stops before anything is pushed and keeps the local commit; a target sync failure after a successful push is reported separately so the user knows the remote is already updated. It never rebases or force-pushes. commit rejects --pull instead of silently ignoring it, since both commands share the argument parser.

* docs(push): document push --pull across guides and translations

Cover the new flag on the push reference, the cross-machine sync guide, the quick reference, the daily workflow and the cross-machine recipe, in English and the ja, ko, zh-Hans and zh-Hant translations, plus the built-in skill's sync reference.

* fix(push): print the scope's sync command when --pull sync fails

A bare 'skillshare sync' retry hint defaults to skills and may pick project mode, so it does not redo an agents, extras, or root sync. Derive both the sync and the hint from one per-scope list.

* fix(pull): sync extras for the root git scope

The root scope versions skills, agents and extras, but pull and push --pull only synced skills and agents, so merged extras changes never reached their targets.

* fix(server): sync extras after a root-scope pull

The root scope versions extras too, but the dashboard pull only synced skills and agents, so merged extras never reached their targets. Matches the CLI fix.

* feat(ui): add a Sync both ways action to Git Sync

Mirrors skillshare push --pull: commit local changes, merge the remote and sync targets, then push, in one click. A pull conflict stops at the existing review before anything is pushed.

* feat(ui): confirm Sync both ways and list what it will do

Sync both ways commits, merges and pushes in one click, so ask first and show the concrete outcome (files to commit, remote commits to merge, scope, push target, conflict behavior) before changing anything.

* fix(ui): make Sync both ways match push --pull

It skipped target sync when the pull was already up to date, stopped on an empty remote instead of pushing, and the pull dropped extras warnings. Add alwaysSync and a remote_empty code to /api/pull and surface all extras warnings.
2026-10-03 18:53:08 +08:00

244 lines
8.3 KiB
Markdown

---
sidebar_position: 4
---
# Quick Reference
Command cheat sheet for skillshare.
## Core Commands
| Command | Description |
|---------|-------------|
| `init` | First-time setup |
| `install <source>` | Add a skill |
| `uninstall <name>...` | Remove one or more skills |
| `list` | List all skills |
| `search <query>` | Search for skills |
| `sync` | Push to all targets |
| `status` | Show sync state |
## Skill Management
| Command | Description |
|---------|-------------|
| `new <name>` | Create a new skill |
| `update <name>` | Update a skill (git pull) |
| `update --all` | Update all tracked repos |
| `check` | Check for skill updates |
| `check --json` | Check for updates (JSON output) |
| `upgrade` | Upgrade CLI and built-in skill |
| `hub list` | List configured skill hubs |
| `hub add <url>` | Add a skill hub |
## Target Management
| Command | Description |
|---------|-------------|
| `target list` | List all targets |
| `target <name>` | Show target details |
| `target <name> --mode <mode>` | Change sync mode |
| `target add <name> <path>` | Add custom target |
| `target remove <name>` | Remove target safely |
| `diff [target]` | Show differences |
## Extras Management
| Command | Description |
|---------|-------------|
| `extras init <name> --target <path>` | Add an extras entry to config |
| `extras init <name> --file <file> --target <path>` | Add an extra that syncs one file (`--as` renames it at targets) |
| `extras list` | List configured extras with sync status |
| `extras remove <name>` | Remove an extras entry from config |
| `extras <name> --add-target <path>` | Add a target to an existing extras entry |
| `extras <name> --remove-target <path>` | Remove a target (add `--prune` to delete synced files) |
| `extras collect <name>` | Collect local files from extras target into source |
## Agent Management
| Command | Description |
|---------|-------------|
| `list agents` | List installed agents |
| `install <source> --kind agent` | Install only agents from a repo |
| `install <source> -a <name>` | Install specific agent(s) by name |
| `uninstall --kind agent <name>` | Remove an agent |
| `sync agents` | Sync only agents to targets |
| `check agents` | Check agents for updates |
| `audit agents` | Security scan agents |
| `enable --kind agent <name>` | Re-enable a disabled agent |
| `disable --kind agent <name>` | Disable an agent via `.agentignore` |
## Plugin Management
| Command | Description |
|---------|-------------|
| `plugin` | Open the interactive plugin manager |
| `plugin list` | Show managed plugins and native installation state |
| `plugin discover <source>` | Inspect a directory or Git repository |
| `plugin add [source]` | Install a complete native plugin |
| `plugin import [plugin@market] --from claude` | Adopt an existing native installation |
| `plugin inspect <name>` | Inspect a managed package |
| `plugin check [name]` | Check source changes without applying |
| `plugin update [name] --target claude` | Update a supported target from a reviewed source |
| `plugin enable [name] --target codex` | Select a target for the next sync |
| `plugin disable [name] --target codex` | Deselect a target for the next sync |
| `plugin remove [name]` | Uninstall managed bindings and remove definitions |
| `sync plugins [name]` | Apply plugin sync selection; alias for `plugin sync` |
Targets: Claude Code, Codex, Cursor, Antigravity (`agy`), Pi, and OpenCode.
Project mode supports Claude, Antigravity, Pi, and OpenCode.
Enable/disable only saves the selection. The next plugin sync installs selected
bindings or uninstalls deselected bindings while retaining their definitions.
Plugins are excluded from `sync --all`. Use `--dry-run --json` to preview mutations;
use `--no-tui` with explicit inputs for automation. See [plugin](../reference/commands/plugin.md)
for native client requirements and supported targets.
## Sync Operations
| Command | Description |
|---------|-------------|
| `sync extras` | Sync non-skill resources (rules, commands, etc.) |
| `sync mcp` | Sync MCP connection settings |
| `hooks list` | List managed native hooks |
| `sync hooks` | Sync native hooks without executing them |
| `sync --all` | Sync skills + agents + extras + MCP + hooks (excludes plugins) |
| `collect <target>` | Collect skills from target to source |
| `collect --all` | Collect from all targets |
| `backup [target]` | Create backup |
| `backup --list` | List backups |
| `restore <target>` | Restore from backup |
| `commit [-m "msg"]` | Create a local git commit without pushing |
| `push [-m "msg"] [--pull]` | Commit and push to git remote; `--pull` merges remote changes first, then syncs |
| `pull` | Pull from git and sync |
| `trash list` | List soft-deleted skills |
| `trash restore <name>` | Restore a soft-deleted skill |
## Utilities
| Command | Description |
|---------|-------------|
| `analyze` | Analyze context window usage (interactive TUI) |
| `analyze --filter <text>` | Filter skills by name/path substring |
| `analyze --json` | Context usage as JSON |
| `doctor` | Diagnose issues |
| `doctor --json` | Diagnose issues (JSON output for CI) |
| `log` | View operations and audit logs |
| `ui` | Launch web dashboard on `localhost:19420` |
| `ui -p` | Launch web dashboard in project mode |
| `completion <shell> --install` | Install shell tab-completion (bash/zsh/fish/powershell/nushell) |
| `version` | Show CLI version |
| `make test-docker` | Run offline Docker sandbox tests |
| `make playground` | Start playground + enter shell (one step) |
| `make playground-down` | Stop and remove playground |
| `./scripts/sandbox.sh <cmd>` | Advanced sandbox management (up/down/shell/reset/status/logs/bare) |
| `make ui-build` | Build frontend |
| `make build-all` | Full binary with frontend |
---
## Common Workflows
### Install and sync a skill
```bash
skillshare install anthropics/skills/skills/pdf
skillshare sync
```
### Create and deploy a skill
```bash
skillshare new my-skill
# Edit ~/.config/skillshare/skills/my-skill/SKILL.md
skillshare sync
```
### Cross-machine sync
```bash
# Setup (pick one)
# Interactive (guided prompts)
skillshare init --remote git@github.com:you/my-skills.git
# Non-interactive (no prompts, auto-detect installed targets)
skillshare init --remote git@github.com:you/my-skills.git --no-copy --all-targets --no-skill
# Optional local checkpoint without pushing
skillshare commit -m "Save local skill edits"
# Machine A: push changes
skillshare push -m "Add new skill"
# Machine B: pull and sync
skillshare pull
# Editing on several machines: both ways in one command
skillshare push --pull -m "Update skills"
```
Optional later (only if you install additional AI CLIs after setup):
```bash
skillshare init --discover
```
With mode override during discover, only newly added targets are affected:
```bash
skillshare init --discover --select cursor --mode copy
```
### Team skill sharing
```bash
# Install team repo
skillshare install github.com/team/skills --track
# Install from specific branch (works with or without --track)
skillshare install github.com/team/skills --branch develop --all
skillshare install github.com/team/skills --track --branch develop
# Pin to a tag or commit SHA (regular install only)
skillshare install github.com/team/skills --branch v1.2.0 --all
# Update from team
skillshare update --all
skillshare sync
```
### Sandbox playground session
```bash
make playground # start + enter shell
skillshare --help
ss status
exit # leave shell
make playground-down # stop container
```
---
## Key Paths
| Path | Description |
|------|-------------|
| `~/.config/skillshare/config.yaml` | Configuration file |
| `~/.config/skillshare/skills/.metadata.json` | Installed skill metadata (auto-managed) |
| `~/.config/skillshare/skills/` | Skill source directory |
| `~/.config/skillshare/agents/` | Agent source directory |
| `~/.config/skillshare/extras/<name>/` | Extras source directories |
| `~/.local/state/skillshare/logs/` | Operation and audit logs |
| `~/.local/share/skillshare/backups/` | Backup directory |
---
## Flags Available on Most Commands
| Flag | Description |
|------|-------------|
| `--dry-run`, `-n` | Preview without making changes |
| `--help`, `-h` | Show help |
---
## See Also
- [Commands Reference](/docs/reference/commands) — Full command documentation
- [Concepts](/docs/understand) — Core concepts explained