# forc-wallet: a CLI wallet for Fuel accounts, signing and key export

> forc-wallet is a Rust CLI that ships as a forc plugin, derives Fuel accounts from a mnemonic, and signs transaction IDs, strings, files or hex payloads. It is a command-line key tool, not a browser wallet, and the README leaves recovery and rollback largely unexplained.

**FuelLabs/forc-wallet** — A forc plugin for managing Fuel wallets.

- Repository: https://github.com/FuelLabs/forc-wallet
- Stars: 100 · Forks: 58
- Language: Rust
- License: not declared
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/fuellabs-forc-wallet

## The gap forc-wallet fills for Fuel developers

Fuel tooling centres on forc, the build and package tool for Sway contracts. That leaves a practical hole: once you have a contract or a transaction, something has to hold the key that signs it. forc-wallet is that something, packaged as a forc plugin so it sits next to the compiler in the same toolchain rather than in a separate install.

The audience is narrow and identifiable. You are writing scripts or CI jobs that need to sign a transaction ID produced by forc-client, or you are a developer who wants deterministic account derivation from one mnemonic instead of pasting private keys around. The README's own framing is modest: "A forc plugin for managing Fuel wallets." It does not claim to be a user-facing wallet application, and it is not one. There is no GUI, no network switcher, no balance display, and no transaction broadcasting in the commands the README lists. It creates keys, derives addresses, and signs bytes. Everything else is somebody else's job.

## How derivation and keystore storage actually work

The mechanism is deterministic derivation, and the README is explicit that account creation is not really creation. Quoting it: "When we 'create' an account, we are really just revealing it." Accounts come from the wallet's mnemonic phrase and a derivation path, so the same mnemonic reproduces the same sequence of accounts on any machine. What forc-wallet adds locally is a cache: it stores the public addresses of accounts it has derived under ~/.fuel/wallets/accounts. That cache is a convenience for listing, not the source of truth. If you delete it, the accounts still exist as long as the mnemonic does.

The wallet file itself follows the Web3 Secret Storage Definition, which the README says forc-wallet adheres to and accepts when importing. That is a meaningful design choice: the encrypted keystore format is the Ethereum one, not a Fuel-specific container, so a file that follows the standard can be handed to forc-wallet. The Cargo.toml confirms the implementation detail, listing eth-keystore as a dependency alongside fuels and forc-tracing.

Signing is split into two entry points. The account-scoped form takes an index and a payload type, and the top-level sign subcommand does the same work with an --account flag. The sign subcommand additionally accepts --private-key, which bypasses the wallet file entirely. That second path matters for automation: it means you can sign without a keystore and a password, at the cost of handling raw key material yourself.

## Installing forc-wallet and signing your first payload

The README recommends fuelup, the Fuel toolchain installer, because forc-wallet is packaged with the default distributed toolchains. If you already have the latest toolchain, the binary should be present. Installing the toolchain and checking the version looks like this:

```bash
fuelup toolchain install latest
forc-wallet --version
```

The README shows the expected output as a version line such as forc-wallet 0.2.2. Treat that string as illustrative of the format rather than as the version you will get; the repository's Cargo.toml declares version 0.15.2, and the most recent release listed is v0.15.2. If you use a custom toolchain instead of the default, add the component explicitly:

```bash
fuelup component add forc-wallet
```

Without fuelup, install from crates.io with cargo:

```bash
cargo install forc-wallet
```

Creating a wallet prompts for a password used to encrypt the file, then prints the mnemonic phrase. The README warns that you need the password for signing and account derivation, and the mnemonic if you want to recover the wallet later. Then derive an account and list what you have:

```bash
forc-wallet new
forc-wallet account new
forc-wallet accounts
```

Signing a transaction ID is a single command once you have the ID from forc-client. The README's example is:

```bash
forc-wallet account <account_index> sign tx-id <transaction_id>
```

For arbitrary payloads the same account-scoped form accepts a string, a file path, or a hex byte string. The hex variant is the easiest to verify, because you can compare the input and output directly:

```bash
forc-wallet account <account_index> sign hex 0x0123456789ABCDEF
```

If you prefer a flat command shape, the README notes that the following is equivalent:

```bash
forc-wallet sign --account <account_index> hex 0x0123456789ABCDEF
```

## Where forc-wallet is the wrong tool

The clearest limitation is that this is a hot wallet driven by a password typed into a terminal. The README states plainly that you need the password for signing and derivation. There is no mention of hardware wallet support, no mention of a passphrase-protected second factor beyond the keystore password, and no mention of any recovery mechanism if the password is lost. The mnemonic is the only documented fallback, and the README does not describe a password reset or a keystore re-encryption command.

A second boundary is the cache directory. Because derived addresses are cached under ~/.fuel/wallets/accounts, anyone with read access to that path and the password can enumerate what you have derived. That is a normal trade-off for a CLI, but it means shared CI runners need thought: the --private-key path on the sign subcommand exists precisely for cases where you do not want a keystore on disk, but it moves the secret-handling problem to your environment variables or secret store rather than solving it.

Finally, the README is silent on several operational questions. It does not document a command to delete an account from the cache, it does not document rollback if a signing operation is interrupted, and it does not state which derivation path is used. If your workflow depends on matching addresses against another wallet implementation, that silence is a real risk, and you should verify the derivation empirically before committing to it.

## forc-wallet compared with the fuels-rs wallet path

The honest alternative is not another CLI, it is the library. The Cargo.toml shows forc-wallet depends on fuels 0.75 from the fuels-rs repository, which means the wallet and signing primitives it exposes are available to any Rust program that links fuels directly. The difference in approach is where the secret lives. forc-wallet puts a keystore file and a password prompt between the key and the caller, and gives you a shell interface. A Rust program using fuels embeds the wallet in its own process, so it can hold a signer in memory and sign without shelling out or re-entering a password.

That matters for two scenarios. In a long-running service, spawning forc-wallet per transaction adds a process boundary and a password input path that a linked signer avoids. In a test suite, the dev-dependencies tell a similar story: forc-wallet's own tests pull in fuel-core-client, tempfile and wiremock, which suggests the project tests against a mocked or local node rather than a live network. If you are writing integration tests, building on fuels directly lets you construct signers in code.

The counter-argument is real. forc-wallet gives you a working keystore, a stable CLI surface, and account caching without writing any of it. For a developer who wants to sign a transaction ID from a shell script, reimplementing that in Rust is wasted effort.

## Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2025-10-06, which coincides with the v0.15.2 release. The two prior releases, v0.15.1 and v0.15.0, landed on 2025-06-19 and 2025-06-12. So the release cadence visible in the repository is a cluster in June followed by a single October release. That is a slow but not abandoned rhythm, and the version numbers suggest the project is still pre-1.0, which is worth factoring into any dependency decision.

Licensing is clearer than the repository metadata suggests. The description field in the repository listing gives the licence as unknown, but the Cargo.toml declares license = "Apache-2.0" and points homepage at https://fuel.network/. For most users Apache-2.0 is permissive and unremarkable; if you redistribute a modified binary or bundle it into a product, read the licence text itself rather than this summary, since nothing here is legal advice.

The upgrade cost is concentrated in the dependency graph. forc-wallet pins fuels 0.75 and forc-tracing 0.68, and the crate is compiled with edition 2024. Because the wallet file format follows the Web3 Secret Storage Definition rather than a bespoke format, upgrading the binary should not invalidate existing keystores, but the README gives no explicit compatibility guarantee across versions. The practical check before upgrading is to confirm that your fuelup toolchain and your forc-client version still agree on the transaction format you are signing, because signing a transaction ID only works if the ID was produced by a compatible tool.

## Conclusion

Adopt forc-wallet if you are already building on Fuel and want account derivation and signing from a terminal or a script, and you are prepared to manage the password and mnemonic yourself. Do not adopt it if you need a browser or hardware-wallet signing flow, or if you expect the tool to recover a lost keystore. Before relying on it, confirm the licence terms for your distribution, check that your fuelup toolchain actually exposes the version you expect with forc-wallet --version, and back up the mnemonic and the files under ~/.fuel/wallets, because the README documents no rollback path for a lost password.

## FAQ

### How do I install forc-wallet?

The README recommends fuelup, since forc-wallet ships with the default distributed toolchains; installing the latest toolchain should make the binary available. If you use a custom toolchain, run fuelup component add forc-wallet, or install it from crates.io with cargo install forc-wallet.

### Where does forc-wallet store my accounts?

The README states that forc-wallet caches the public addresses of derived accounts within ~/.fuel/wallets/accounts. The accounts themselves are derived deterministically from the wallet's mnemonic phrase and derivation path, so the cache is a local convenience rather than the source of truth.

### Can I sign data without a wallet file in forc-wallet?

Yes. The README documents that the sign subcommand accepts a --private-key option, letting you sign directly with a private key instead of a wallet account. The same subcommand also accepts an --account flag when you do want to use a derived account.

## Sources

- [Official README](https://github.com/FuelLabs/forc-wallet#readme)
- [Project repository](https://github.com/FuelLabs/forc-wallet)
- [Release notes](https://github.com/FuelLabs/forc-wallet/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/fuellabs-forc-wallet