skillsync
Docs/Skillsync CLI

Troubleshoot the Skillsync CLI

Fix local session discovery, continuation, login, session sync, skills, MCP, and installation problems.

These docs cover the current Skillsync CLI. Local session support is powered by the open-source txcript project.

Start by checking the installed version and command-specific help:

skl --version
skl <command> --help

Command not found

Open a new terminal after installation so your shell reloads PATH. Then locate the binary:

which skl

On Windows PowerShell:

where.exe skl

If needed, run the installer again or use skl update from a shell where the command is already available.

Update fails or leaves a broken binary

Reinstall over it. The installer replaces the binary and keeps your login and settings:

curl -fsSL https://install.skillsync.com/install.sh | sh

irm https://install.skillsync.com/install.ps1 | iex

Confirm with skl --version and skl whoami; run skl init if the account is missing. Set SKL_NO_UPDATE_CHECK=1 if the automatic update check itself is the problem.

Session source is missing

First check whether the source appears without filters:

skl list
skl list --from <agent>

Confirm that the agent's session store exists and is readable by the current user. Common locations are listed in /docs/transcript-support.

On macOS, terminals without Full Disk Access may be unable to read session files under protected directories. Grant access to the terminal application in System Settings, then restart it.

Session ID or title is not found

Use skl list or skl query to recover the ID. Commands accept a full ID, an unambiguous ID prefix, or an exact title.

skl query "part of the title"
skl view <id>

If multiple agents use similar IDs, add --from <agent>.

Search misses expected content

Remove --cwd and --from filters first. skl query searches all known sources and directories by default.

The persistent search cache is rebuilt when sessions change. If results appear stale, update the CLI and retry:

skl update
skl query "expected text"

Continue does not launch an agent

Confirm the target agent's CLI is installed and on PATH. To test conversion without launching it:

skl continue <id> --with <agent> --no-resume

Not every source can be a continuation target. Amp and Hermes are source-only in the current CLI. See /docs/transcript-support and the txcript compatibility matrix.

Login fails or expires

Check the active account:

skl whoami

Sign in again if the credentials are expired:

skl login

Use device login on SSH, headless machines, or when the local browser callback cannot complete:

skl login --device

If SKL_TOKEN is set, it overrides stored browser credentials. skl logout removes the credentials file but cannot unset the environment variable.

A session cannot be synced

Validate it without sending anything:

skl sync <id> --dry-run

Common causes, each reported before any request is made:

  • Not logged in: run skl login, or set SKL_TOKEN.
  • Ignored path: the session is under a path hidden with skl ignore. Run skl ignore remove <path>.
  • Unsupported source: Skillsync does not accept every agent yet; check the sync column in /docs/transcript-support.
  • No exportable messages: the session is empty or contains nothing the thread format can carry.
  • Too large: the session exceeds the server limit after compression. Sync a shorter session, or continue it into a new one and sync that.

If the shares look wrong, remember that a re-sync with no --workspace or --private keeps the existing set, and that skl remote set-default applies only to a session's first sync. Pass the flags explicitly to override either.

A synced session cannot be found

skl remote accepts a local session ID only when that session was synced from this machine. On another machine, or after the local sync map is lost, use the thread slug instead:

skl remote list
skl remote open <slug>

A prefix that matches several synced sessions is rejected; use a longer one.

A skill cannot be installed

Inspect the remote skill and verify authentication:

skl whoami
skl skills show <reference>

An existing destination is not replaced automatically in non-interactive use. Inspect it, then use --force only when replacement is intentional:

skl skills install <reference> --force

A local skill cannot be published

Validate it without network access:

skl skills upload <skill-or-path> --dry-run

The skill needs a SKILL.md with a non-empty Markdown body and a description frontmatter field. Add --project when resolving a project-local skill by name.

MCP client cannot connect

Run skl mcp directly only as a protocol process; it waits for JSON-RPC on stdin and normally prints nothing for a human. Check the MCP client's logs and use an absolute binary path if it cannot resolve skl.

See /docs/mcp-server for configuration examples and the exact tools.

A documented command is missing

Older Skillsync docs described session commands named upload, auto, and watch. They are not part of the current CLI. Update skl, use skl --help as the installed command contract, and use list, query, view, or continue for local sessions. To publish a session, run skl sync <id>; if your installed skl lacks sync or remote, run skl update.