Skip to content

MARKDOWN SOURCE

Raw
# Tree

Tree is the command-line companion for managing access to Twig.

## Sign in

```sh
tree auth
```

Tree defaults to `https://twig.silenlocatelli.ch/`. Enter another Twig URL at
the prompt or pass one directly:

```sh
tree auth --url https://twig.example.com/
```

Tree opens Twig in your browser. Sign in, compare the displayed code with the
one in your terminal, then choose the namespaces and actions to grant. Twig
creates a scoped `Tree CLI` access token. Tree stores it in the operating
system's credential store; it is not printed or written to Git configuration.

After approval, Tree configures Git's global credential helper only for the
authorized Twig URL. HTTP(S) repository URLs on that server can then use the
selected token permissions. Git helper setup is URL- and path-aware and does
not replace unrelated global helpers.

## Check status

```sh
tree status
```

Status reports whether a token is stored locally for the default Twig server,
whether its `/up` endpoint responds with HTTP 200, and the running application
version returned by the authenticated `/api/version` endpoint. If no token is
saved, Tree skips that API request; a rejected token appears as an unavailable
version. Pass `--url https://twig.example.com/` to check another server. The
authentication result reports whether a local token is saved; it does not
independently validate that token.

## Use the Twig API

After `tree auth`, Tree uses the saved scoped token as a Bearer credential for
every API request. API operations require authentication even when a namespace
or repository is publicly viewable in Twig. All structured responses are
printed as pretty JSON. `--url` can be used before or after a command.

```sh
tree me
tree version
tree namespace list
tree namespace create acme
tree namespace show acme
tree namespace rename acme acme-tools
tree namespace delete acme-tools

tree repo list acme --query tools
tree repo create acme tooling --default-branch main
tree repo show acme tooling
tree repo rename acme tooling developer-tools
tree repo move acme tooling other-namespace
tree repo branches acme tooling
tree repo commits acme tooling --ref feature/docs --limit 20
tree repo tree acme tooling --ref main --path src
tree repo delete other-namespace tooling
```

Repository content reads return the API's Base64 JSON by default. Use `--output`
to decode a file directly. Content writes require the current branch head and a
commit message; the server rejects stale heads rather than overwriting newer
work. Provide either `--text` (UTF-8) or `--file` (arbitrary bytes, sent as
Base64). Content is limited to 1 MiB per operation.

```sh
tree content get acme tooling --ref main README.md --output README.md
tree content put acme tooling --ref main README.md --text 'Hello from Tree' \
  --message 'Update README' --expected-head '<current-commit-id>'
tree content put acme tooling --ref main assets/logo.bin --file ./logo.bin \
  --message 'Add logo' --expected-head '<current-commit-id>'
tree content delete acme tooling --ref main old.txt \
  --message 'Remove old file' --expected-head '<current-commit-id>'
tree content rename acme tooling --ref main old.txt new.txt \
  --message 'Rename file' --expected-head '<current-commit-id>'
```

Binary releases are transferred as raw bytes. Uploads are limited to 512 MiB;
downloads require an output file path. Twig applies safe-filename checks and
retains its three highest SemVer releases; `latest` can be used for downloads.

```sh
tree binary list acme tooling
tree binary put acme tooling 1.2.3 tool-linux-amd64 --file ./tool-linux-amd64
tree binary get acme tooling latest tool-linux-amd64 --output ./tool-linux-amd64
```

Namespace member and invitation operations are also available:

```sh
tree member list acme
tree invitation list acme
tree invitation create acme person@example.com contributor 7d
tree invitation resend acme '<invitation-id>'
```

Invitation roles are `owner` or `contributor`; expiry is `1d`, `7d`, `30d`, or
`never`. Twig remains authoritative for permissions, resource visibility,
deletability, path safety, and conflicts. Tree does not retry stale content
mutations.

## Revoke or refresh access

Revoke a `Tree CLI` token from Twig Account Settings → Access Tokens. Running
`tree auth` again creates a new token; revoke older tokens there if you no
longer need them. When Git invokes the helper's `erase` operation after an
authentication failure, Tree forgets the matching local copy. A secure
operating-system credential store and Git must be available. HTTP is
accepted only for loopback development URLs; use HTTPS for other Twig servers.

Tree never falls back to a plaintext token file. If the keyring is unavailable,
sign-in stops before contacting Twig. If saving a token or updating Git's global
config fails after approval, follow the error guidance and revoke any unused
`Tree CLI` token in Twig Settings.

The former Fig tree display and repository-clone commands have been removed.

## Simulation test suite

Run Tree's simulation suite with:

```sh
cargo run --features testing
```

The suite exercises authorization success and denial, verification-URL safety,
Git credential get/erase/store behavior, authenticated API command scenarios,
and status reporting including a fake Twig version. It prints each scenario and a pass/fail summary; any failed
scenario makes the command exit unsuccessfully.
The `testing` feature uses only local fake implementations: it does not contact
Twig, open a browser, access the OS keyring, invoke Git, or change machine
credentials or Git configuration. Explicit commands such as `auth` also use
fakes when this feature is enabled. Run Tree without the feature for normal
production behavior.

Tree

Tree is the command-line companion for managing access to Twig.

Sign in

tree auth

Tree defaults to https://twig.silenlocatelli.ch/. Enter another Twig URL at the prompt or pass one directly:

tree auth --url https://twig.example.com/

Tree opens Twig in your browser. Sign in, compare the displayed code with the one in your terminal, then choose the namespaces and actions to grant. Twig creates a scoped Tree CLI access token. Tree stores it in the operating system's credential store; it is not printed or written to Git configuration.

After approval, Tree configures Git's global credential helper only for the authorized Twig URL. HTTP(S) repository URLs on that server can then use the selected token permissions. Git helper setup is URL- and path-aware and does not replace unrelated global helpers.

Check status

tree status

Status reports whether a token is stored locally for the default Twig server, whether its /up endpoint responds with HTTP 200, and the running application version returned by the authenticated /api/version endpoint. If no token is saved, Tree skips that API request; a rejected token appears as an unavailable version. Pass --url https://twig.example.com/ to check another server. The authentication result reports whether a local token is saved; it does not independently validate that token.

Use the Twig API

After tree auth, Tree uses the saved scoped token as a Bearer credential for every API request. API operations require authentication even when a namespace or repository is publicly viewable in Twig. All structured responses are printed as pretty JSON. --url can be used before or after a command.

tree me
tree version
tree namespace list
tree namespace create acme
tree namespace show acme
tree namespace rename acme acme-tools
tree namespace delete acme-tools

tree repo list acme --query tools
tree repo create acme tooling --default-branch main
tree repo show acme tooling
tree repo rename acme tooling developer-tools
tree repo move acme tooling other-namespace
tree repo branches acme tooling
tree repo commits acme tooling --ref feature/docs --limit 20
tree repo tree acme tooling --ref main --path src
tree repo delete other-namespace tooling

Repository content reads return the API's Base64 JSON by default. Use --output to decode a file directly. Content writes require the current branch head and a commit message; the server rejects stale heads rather than overwriting newer work. Provide either --text (UTF-8) or --file (arbitrary bytes, sent as Base64). Content is limited to 1 MiB per operation.

tree content get acme tooling --ref main README.md --output README.md
tree content put acme tooling --ref main README.md --text 'Hello from Tree' \
  --message 'Update README' --expected-head '<current-commit-id>'
tree content put acme tooling --ref main assets/logo.bin --file ./logo.bin \
  --message 'Add logo' --expected-head '<current-commit-id>'
tree content delete acme tooling --ref main old.txt \
  --message 'Remove old file' --expected-head '<current-commit-id>'
tree content rename acme tooling --ref main old.txt new.txt \
  --message 'Rename file' --expected-head '<current-commit-id>'

Binary releases are transferred as raw bytes. Uploads are limited to 512 MiB; downloads require an output file path. Twig applies safe-filename checks and retains its three highest SemVer releases; latest can be used for downloads.

tree binary list acme tooling
tree binary put acme tooling 1.2.3 tool-linux-amd64 --file ./tool-linux-amd64
tree binary get acme tooling latest tool-linux-amd64 --output ./tool-linux-amd64

Namespace member and invitation operations are also available:

tree member list acme
tree invitation list acme
tree invitation create acme person@example.com contributor 7d
tree invitation resend acme '<invitation-id>'

Invitation roles are owner or contributor; expiry is 1d, 7d, 30d, or never. Twig remains authoritative for permissions, resource visibility, deletability, path safety, and conflicts. Tree does not retry stale content mutations.

Revoke or refresh access

Revoke a Tree CLI token from Twig Account Settings → Access Tokens. Running tree auth again creates a new token; revoke older tokens there if you no longer need them. When Git invokes the helper's erase operation after an authentication failure, Tree forgets the matching local copy. A secure operating-system credential store and Git must be available. HTTP is accepted only for loopback development URLs; use HTTPS for other Twig servers.

Tree never falls back to a plaintext token file. If the keyring is unavailable, sign-in stops before contacting Twig. If saving a token or updating Git's global config fails after approval, follow the error guidance and revoke any unused Tree CLI token in Twig Settings.

The former Fig tree display and repository-clone commands have been removed.

Simulation test suite

Run Tree's simulation suite with:

cargo run --features testing

The suite exercises authorization success and denial, verification-URL safety, Git credential get/erase/store behavior, authenticated API command scenarios, and status reporting including a fake Twig version. It prints each scenario and a pass/fail summary; any failed scenario makes the command exit unsuccessfully. The testing feature uses only local fake implementations: it does not contact Twig, open a browser, access the OS keyring, invoke Git, or change machine credentials or Git configuration. Explicit commands such as auth also use fakes when this feature is enabled. Run Tree without the feature for normal production behavior.