yungle-cli 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +122 -40
  3. package/dist/yungle.mjs +2973 -377
  4. package/package.json +22 -17
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 Hein de Wilde
3
+ Copyright (c) 2026 Brainpower
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,64 +1,146 @@
1
1
  # yungle-cli
2
2
 
3
- Send and sync files with [Yungle](https://yungle.co) from the command line.
3
+ Send, receive and sync large files with [Yungle](https://yungle.co?ref=npm) from your terminal
4
+ or CI. Resumable uploads up to 100 GB, private and EU-hosted.
5
+
6
+ <img src="https://raw.githubusercontent.com/heindewilde/yungle-clients/main/.github/assets/demo.svg" alt="yungle send, yungle status and yungle get in a terminal" width="720">
4
7
 
5
8
  ```bash
6
9
  npm install -g yungle-cli
7
- yungle auth login
8
- yungle send ~/Shoot --to client@example.com
10
+ yungle login # opens your browser, once
11
+ yungle send ~/Shoot # uploads resumably, prints the link
9
12
  ```
10
13
 
11
- ## Why a CLI
12
-
13
- Yungle's upload engine is resumable at part granularity and sized for 100 GB
14
- transfers. Until this existed, the only thing that could drive it was a browser
15
- tab that had to stay open — which is the wrong process to hand an eight-hour
16
- upload to. This one survives a closed laptop lid: interrupt `yungle send`, run
17
- the same command again, and it continues from the last committed part instead of
18
- starting over.
14
+ Works on the free plan. Node 22 or newer.
19
15
 
20
16
  ## Commands
21
17
 
18
+ **Get started**
19
+
20
+ | | |
21
+ |---|---|
22
+ | `yungle login` | Sign in with your browser. `--key` uses an API key instead (servers, CI) |
23
+ | `yungle whoami` | Who you are signed in as, and what you may do |
24
+ | `yungle logout` | Sign out and revoke the session |
25
+
26
+ **Send and receive**
27
+
22
28
  | | |
23
29
  |---|---|
24
- | `yungle auth login` | Save an API key (or set `YUNGLE_API_KEY`) |
25
- | `yungle auth status` | Which key is in use, and what it may do |
26
- | `yungle send <paths…>` | Send files; prints the share link |
27
- | `yungle push <paths…> --collection <id>` | Upload into a collection |
28
- | `yungle ls transfers\|collections\|contacts` | List things |
29
- | `yungle rm transfer <id>` | Revoke a transfer |
30
+ | `yungle send <paths…>` | Send files or folders and print the link. `--to`, `--message`, `--title`, `--password`, `--expires` |
31
+ | `yungle get <link>` | Download a transfer sent to you. No account needed. `--out`, `--zip`, `--password` |
32
+ | `yungle status [<id\|link>]` | Who opened and downloaded a transfer. Without an id, pick from your recent ones |
33
+ | `yungle transfers` | Your recent transfers |
34
+ | `yungle revoke <id>` | Stop a transfer's link for good (asks first) |
35
+
36
+ **Collections** (paid plans)
37
+
38
+ | | |
39
+ |---|---|
40
+ | `yungle push <paths…> --collection <id>` | Upload into a collection, optionally `--folder <id>` |
41
+ | `yungle watch <dir> --collection <id>` | Keep uploading new files as they appear |
42
+ | `yungle collections` | Your collections |
43
+ | `yungle contacts` | Your contacts |
44
+
45
+ **Everything else**
46
+
47
+ | | |
48
+ |---|---|
49
+ | `yungle open [<id>\|plan\|keys\|webhooks]` | Open the dashboard, or a transfer, in your browser |
50
+ | `yungle webhooks ls` · `listen` | List endpoints, or print events live and `--forward-to` a local server |
51
+ | `yungle mcp install` · `status` | Connect a local AI assistant (see below) |
52
+ | `yungle completion <zsh\|bash\|fish>` | Tab completion |
53
+
54
+ Ids can be shortened: the last 6–8 characters of a transfer id, or its link, work everywhere
55
+ an id does. `yungle <command> --help` shows examples. Old spellings (`auth login`,
56
+ `ls transfers`, `rm transfer`) keep working.
57
+
58
+ ## For people, and for scripts
59
+
60
+ The same command behaves right in both places:
61
+
62
+ | | At a terminal | In a pipe or CI | With `--json` |
63
+ |---|---|---|---|
64
+ | Output | Colour, tables, a live progress bar | Plain text; `send` prints only the link | One JSON object on stdout |
65
+ | Missing arguments | Asks, step by step | Fails with a usage hint | Fails with a usage hint |
66
+ | Confirmations | Asks | Never asks | Never asks |
30
67
 
31
- `--json` on any command prints a machine-readable object on stdout; progress
32
- goes to stderr, so `yungle send … --json \| jq` works.
68
+ Progress always goes to stderr, so `yungle send dist/ | pbcopy` copies just the link and
69
+ `yungle send dist/ --json | jq -r .url` works. `--yes` means "never ask", for scripts that run at
70
+ a terminal. `NO_COLOR` and `FORCE_COLOR` are respected.
33
71
 
34
- Folders keep their structure. Hidden files are skipped when walking a directory
35
- and kept when named directly.
72
+ Every error says what happened and the command that fixes it:
73
+
74
+ ```
75
+ ✖ Your sign-in is no longer valid (revoked, expired or mistyped).
76
+ → yungle login
77
+ ```
78
+
79
+ Exit codes: `0` success, `1` failure, `2` usage error, `130` cancelled.
36
80
 
37
81
  ## Resuming
38
82
 
39
- State lives in `~/.cache/yungle/`. A session is keyed by the *local files* —
40
- their paths, sizes and modification times — because that is all the next
41
- invocation has to go on; it cannot know the transfer id of a process that was
42
- killed. Run the same command with the same files and it resumes; change a file
43
- and it starts over, because resuming into a row whose declared size no longer
44
- matches fails at the very end with an error that points nowhere useful.
83
+ Interrupt `yungle send` (Ctrl-C, a dropped connection, a closed lid) and run the same command
84
+ again: it continues from the last committed part instead of starting over.
85
+
86
+ State lives in `~/.cache/yungle/`, keyed by the local files' paths, sizes and modification
87
+ times, since that is all the next run has to go on. Change a file and it starts over, because
88
+ a resumed upload whose declared size no longer matches would fail at the very end. Sessions
89
+ expire after two hours, matching the upload tokens they hold.
90
+
91
+ ## Watching a folder
92
+
93
+ ```bash
94
+ yungle watch ~/Renders --collection 01J8Z3M9Q0W4
95
+ ```
96
+
97
+ For a render box writing frames, a card reader, an export folder. It polls (every 10 seconds,
98
+ `--interval` to change) rather than using file-system events, which are unreliable on network
99
+ shares and external drives. A file is uploaded only once it has stopped changing, so a
100
+ half-written frame never goes up. What was uploaded is remembered, so a restart never uploads
101
+ twice. Files already there when it starts are left alone unless you pass `--existing`.
45
102
 
46
- Sessions expire after two hours, matching the lifetime of the upload tokens
47
- they hold.
103
+ ## Signing in
48
104
 
49
- ## Credentials
105
+ `yungle login` opens your browser, you confirm a code, done. The session is stored in
106
+ `~/.config/yungle/config.json` (mode `0600`) and renews itself.
50
107
 
51
- Read from `YUNGLE_API_KEY` first, then `~/.config/yungle/config.json` (written
52
- `0600`). A key acts as one workspace and can be revoked at any time from
53
- Settings → API keys.
108
+ **A browser sign-in makes links but never emails anyone.** Signing in by code can be phished
109
+ ("enter this code" is the whole attack), so that session can't make Yungle mail strangers or
110
+ register a webhook. `yungle send --to` notices before uploading and offers to send a link
111
+ instead.
54
112
 
55
- The API is available on any paid Yungle plan. Full documentation:
56
- <https://yungle.co/developers>
113
+ To email recipients, and on servers or in CI, use an API key: `yungle login --key` (asks for
114
+ it) or set `YUNGLE_API_KEY`, which always wins over the config file. Create keys under
115
+ [Settings → API keys](https://yungle.co/dashboard/settings/api) or with `yungle open keys`.
116
+
117
+ ## Connecting a local AI assistant
118
+
119
+ The easiest way to connect Claude or Cursor is the hosted server at `https://yungle.co/mcp`:
120
+ add it in the client and sign in, no key involved.
121
+
122
+ To run the MCP server locally instead:
123
+
124
+ ```bash
125
+ yungle login --key # a read-only key is best
126
+ yungle mcp install # or --client claude-code, --dry-run
127
+ ```
128
+
129
+ This writes the [Yungle MCP server](https://www.npmjs.com/package/yungle-mcp) into Claude
130
+ Desktop, Claude Code, Cursor and Windsurf, whichever you have. Restart the client afterwards.
131
+
132
+ - **It wants a real API key**, not a browser session, which expires within the hour. The key
133
+ ends up in the client's config file in plain text, which is how local MCP servers receive
134
+ credentials.
135
+ - **It refuses a key that can write** unless you pass `--allow-write`, which lets the assistant
136
+ create share links (every one still needs your confirmation).
137
+ - **A config file that does not parse is refused, never overwritten.** It holds your other
138
+ MCP servers too. The previous contents are copied to `<config>.yungle-bak` before any change.
57
139
 
58
140
  ## What it cannot do
59
141
 
60
- Your vault and end-to-end encrypted transfers are not reachable through the API
61
- this is built on. Their keys are derived in the client and never sent to us, so
62
- a server-side API has nothing to offer — see
63
- <https://yungle.co/developers/unsupported>. Reaching them from a local client is
64
- possible in principle and is not built yet.
142
+ Your vault and end-to-end encrypted transfers are not reachable: their keys are derived in the
143
+ browser and never sent to Yungle. `yungle get` on an end-to-end encrypted link says so and
144
+ points you to the browser. See <https://yungle.co/developers/unsupported>.
145
+
146
+ Docs: <https://yungle.co/developers/cli?ref=npm> · Source: <https://github.com/heindewilde/yungle-clients> · MIT