CLI overview

The wiele command runs on macOS and Linux. Every command prints help with --help, and the pages in this section list every command and flag the CLI has. The reference is generated from the CLI itself, so it matches the published version.

Global flags

These flags work on every command.

The CLI framework adds a few more:

Names, paths and IDs

You can name most things by ID, slug or name:

• Organizations: ID (org_...) or slug. Pick a default with wiele org use SLUG.
• Workspaces: ID (ws_...), slug or name. A few commands take only the ID; their flag descriptions say so.
• Branches: name or ID (br_...). Without --branch, commands use the checkout's branch, or main outside a checkout.
• Revisions: the full 40-character SHA. Short SHAs and branch names don't work where a revision is expected.

A remote path is written as WORKSPACE:/path, such as my-work:/notes/plan.md. The workspace root is my-work:/. Inside a checkout you can leave out the workspace and organization, and commands take them from the checkout.

Paths can't contain \, control characters or more than 64 levels, and no path component may be .wiele, .wiele-meta, .git, .gitattributes or .lfsconfig.

Output

By default commands print text for people. Errors go to standard error:

error: The branch changed before this push could publish, so the server closed it. Local files are unchanged. (HEAD_MOVED)
next: Run wiele pull, then wiele push again

With --json, every command prints one JSON object on standard output:

{ "schemaVersion": 1, "ok": true, "data": {} }

{
  "schemaVersion": 1,
  "ok": false,
  "error": {
    "code": "HEAD_MOVED",
    "message": "...",
    "retryable": false,
    "nextActions": ["Run wiele pull, then wiele push again"]
  }
}

error may also carry operationId and details. Scripts and agents should pass --json --non-interactive, then check ok and the exit code. Every error code is listed in Troubleshooting.

Exit codes

Retries and waiting

Most commands that change something on the server take --idempotency-key. Each run generates a fresh UUIDv7, except onboarding complete, which needs one passed in. push takes no key. Run it again and it resumes the saved push. If a command times out or the network drops, run it again with the same key: the server returns the first result instead of doing the work twice.

Commands that start server work wait up to 30 seconds by default; each flag table shows the exceptions. Change that with --wait, such as --wait 2m, or return at once with --no-wait where the command has it. A wait that runs out fails with OPERATION_PENDING; the work continues on the server and the same command picks it up.

Environment variables

Local files