siyuan-note/siyuan · error

full-manual mode requires 'push' or 'pull' subcommand

Error message

full-manual mode requires 'push' or 'pull' subcommand

What it means

Thrown by the bare `sync` cobra command when `model.Conf.Sync.Mode == 3` (full-manual mode). In full-manual mode SiYuan never auto-syncs in either direction — the user must explicitly choose push or pull to avoid accidental overwrites. Calling bare `sync` would be ambiguous, so it is rejected and the operator is redirected to the `push` or `pull` subcommands. The mode is read from `conf.json` (`system.sync.mode`) loaded during `model.InitConf`.

Source

Thrown at kernel/cli/cmd/sync.go:35

package cmd

import (
	"encoding/json"
	"fmt"
	"time"

	"github.com/siyuan-note/siyuan/kernel/conf"
	"github.com/siyuan-note/siyuan/kernel/model"

	"github.com/spf13/cobra"
)

var syncCmd = &cobra.Command{
	Use:   "sync",
	Short: "Sync data with cloud",
	RunE: func(cmd *cobra.Command, args []string) error {
		if model.Conf.Sync.Mode == 3 {
			return fmt.Errorf("full-manual mode requires 'push' or 'pull' subcommand")
		}

		if dryRun {
			fmt.Println("[dry-run] Would sync data with cloud")
			return nil
		}

		model.SyncData(true)
		fmt.Println("ok")
		return nil
	},
}

var syncPushCmd = &cobra.Command{
	Use:   "push",
	Short: "Upload to cloud",
	RunE: func(cmd *cobra.Command, args []string) error {
		if dryRun {

View on GitHub (pinned to 251596fc0d)

Solutions

1. Use an explicit subcommand: `siyuan sync push` to upload or `siyuan sync pull` to download.
2. If you want bare `sync` to work, switch the mode back to auto/manual (0/1/2) via the GUI settings or by editing `conf.json`.

Example fix

// before
siyuan sync
// after
siyuan sync push

// Check sync mode before choosing the command shape.
if model.Conf.Sync.Mode == 3 {
    // must use `sync push` or `sync pull` explicitly
    fmt.Println("full-manual mode — use `sync push` or `sync pull`")
} else {
    // `sync` is allowed
}

When it happens

Trigger: Running `siyuan sync` (no subcommand) while the workspace's `conf.json` has `sync.mode` set to 3. Triggered after switching to full-manual sync mode in the GUI settings.

Common situations: User changed sync mode to full-manual in the app settings to prevent auto-sync, then scripted `siyuan sync` expecting bidirectional behavior; CI/automation invoking the bare `sync` command against a workspace configured for manual control.

Related errors

• --id is required
• --file is required
• --path must not be empty
• --path is required
• --id is required

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/6c3b5bca448342b5. Report an issue: GitHub.