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

The `sync` cobra command refuses to run when the workspace sync mode is set to 3 (full-manual). In full-manual mode automatic `siyuan sync` is disabled by design and the user must explicitly choose a direction via the `sync push` or `sync pull` subcommand, so the plain command returns this error instead of syncing.

Solutions

1. Use `siyuan sync push` or `siyuan sync pull` instead of plain `siyuan sync`
2. Change the sync mode away from full-manual (Conf.Sync.Mode != 3) in the workspace settings if bidirectional sync is desired
3. Update automation scripts to detect mode 3 and invoke the directional subcommand

Example fix

// before
siyuan sync
// after
siyuan sync push

if [ "$(siyuan config get sync.mode 2>/dev/null || echo 0)" = "3" ]; then
  exec siyuan sync push
fi
siyuan sync

if ! siyuan sync; then
  echo "sync failed; if in full-manual mode use: siyuan sync push|pull" >&2
  exit 1
fi

When it happens

Trigger: Running `siyuan sync` (no subcommand) while `model.Conf.Sync.Mode == 3` in the workspace configuration.

Common situations: A user switched sync mode to 'full-manual' in the SiYuan settings UI and then still invokes the generic sync command from scripts or cron jobs that were written when mode was auto/on-demand.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• Conf.Language(249)
• Data synchronization has not been enabled
• invalid provider [ ]
• The synchronization function can only be activated after…
• unknown cloud provider

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/6c3b5bca448342b5. Report an issue: GitHub.

Appendix: 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 9f775e8a12)