Skip to content

Commit fbc817f

Browse files
arjankowskiarjankowski
authored
feat: Improve developer and agent experience in boxcli commands (#643)
1 parent a58ff34 commit fbc817f

29 files changed

+258
-70
lines changed

‎docs/ai.md‎

Lines changed: 21 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,14 @@ FLAGS
2525
-t, --token=<value> Provide a token to perform this call
2626
-v, --verbose Show verbose output, which can be helpful for debugging
2727
-y, --yes Automatically respond yes to all confirmation prompts
28-
--ai-agent=<value> The AI agent to be used for the ask, provided as a JSON string. Example: {"type":
29-
"ai_agent_ask", "basicText": {"model": "openai__gpt_3_5_turbo"}}
28+
--ai-agent=<value> AI agent configuration as JSON. Example:
29+
{"type":"ai_agent_ask","basic_text":{"model":"azure__openai__gpt_4o_mini"}}
3030
--as-user=<value> Provide an ID for a user
3131
--bulk-file-path=<value> File path to bulk .csv or .json objects
3232
--csv Output formatted CSV
3333
--fields=<value> Comma separated list of fields to show
34-
--items=<value>... (required) The items for the AI request
34+
--items=<value>... (required) Items for the AI request. Format: id=FILE_ID,type=file (or
35+
content=TEXT,type=file). Supported keys: id, type, content.
3536
--json Output formatted JSON
3637
--no-color Turn off colors for logging
3738
--prompt=<value> (required) The prompt for the AI request
@@ -63,14 +64,15 @@ FLAGS
6364
-t, --token=<value> Provide a token to perform this call
6465
-v, --verbose Show verbose output, which can be helpful for debugging
6566
-y, --yes Automatically respond yes to all confirmation prompts
66-
--ai-agent=<value> The AI agent to be used for the extraction, provided as a JSON string. Example:
67-
{"type": "ai_agent_extract", "basicText": {"model": "azure__openai__gpt_4o_mini",
68-
"promptTemplate": "Answer the question based on {content}"}}
67+
--ai-agent=<value> AI agent configuration as JSON. Example: {"type":"ai_agent_extract","basic_text":{"mo
68+
del":"azure__openai__gpt_4o_mini","prompt_template":"Answer the question based on
69+
{content}"}}
6970
--as-user=<value> Provide an ID for a user
7071
--bulk-file-path=<value> File path to bulk .csv or .json objects
7172
--csv Output formatted CSV
7273
--fields=<value> Comma separated list of fields to show
73-
--items=<value>... (required) The items that LLM will process.
74+
--items=<value>... (required) Items for extraction. Format: id=FILE_ID,type=file (or
75+
content=TEXT,type=file). Supported keys: id, type, content.
7476
--json Output formatted JSON
7577
--no-color Turn off colors for logging
7678
--prompt=<value> (required) The prompt provided to a Large Language Model (LLM) in the request.
@@ -82,7 +84,7 @@ DESCRIPTION
8284
EXAMPLES
8385
$ box ai:extract --items=id=12345,type=file --prompt "firstName, lastName, location, yearOfBirth, company"
8486
85-
$ box ai:extract --prompt "firstName, lastName, location, yearOfBirth, company" --items "id=12345,type=file" --ai-agent '{"type":"ai_agent_extract","basicText":{"llmEndpointParams":{"type":"openai_params","frequencyPenalty": 1.5,"presencePenalty": 1.5,"stop": "<|im_end|>","temperature": 0,"topP": 1},"model": "azure__openai__gpt_4o_mini","numTokensForCompletion": 8400,"promptTemplate": "It is, consider these travel options and answer the.","systemMessage": "You are a helpful travel assistant specialized in budget travel"}}}'
87+
$ box ai:extract --prompt "firstName, lastName, location, yearOfBirth, company" --items "id=12345,type=file" --ai-agent '{"type":"ai_agent_extract","basic_text":{"model":"azure__openai__gpt_4o_mini"}}'
8688
```
8789

8890
_See code: [src/commands/ai/extract.js](https://github.com/box/boxcli/blob/v4.5.0/src/commands/ai/extract.js)_
@@ -104,15 +106,16 @@ FLAGS
104106
-t, --token=<value> Provide a token to perform this call
105107
-v, --verbose Show verbose output, which can be helpful for debugging
106108
-y, --yes Automatically respond yes to all confirmation prompts
107-
--ai-agent=<value> The AI agent to be used for the structured extraction, provided as a JSON string.
108-
Example: {"type": "ai_agent_extract_structured", "basicText": {"model":
109-
"azure__openai__gpt_4o_mini", "promptTemplate": "Answer the question based on
110-
{content}"}}
109+
--ai-agent=<value> AI agent configuration as JSON. Example: {"type":"ai_agent_extract_structured","basic
110+
_text":{"model":"azure__openai__gpt_4o_mini","prompt_template":"Answer the question
111+
based on {content}"}}
111112
--as-user=<value> Provide an ID for a user
112113
--bulk-file-path=<value> File path to bulk .csv or .json objects
113114
--csv Output formatted CSV
114-
--fields=<value>... The fields to be extracted from the provided items.
115-
--items=<value>... (required) The items that LLM will process.
115+
--fields=<value>... Fields to extract from the provided items. Use options=VALUE1;VALUE2 for multiSelect
116+
fields.
117+
--items=<value>... (required) Items for structured extraction. Format: id=FILE_ID,type=file (or
118+
content=TEXT,type=file). Supported keys: id, type, content.
116119
--json Output formatted JSON
117120
--metadata-template=<value> The metadata template containing the fields to extract.
118121
--no-color Turn off colors for logging
@@ -126,7 +129,7 @@ DESCRIPTION
126129
EXAMPLES
127130
$ box ai:extract-structured --items="id=12345,type=file" --fields "key=hobby,type=multiSelect,description=Person hobby,prompt=What is your hobby?,displayName=Hobby,options=Guitar;Books"
128131
129-
$ box ai:extract-structured --items="id=12345,type=file" --metadata-template="type=metadata_template,scope=enterprise,template_key=test" --ai-agent '{"type":"ai_agent_extract_structured","basicText":{"llmEndpointParams":{"type":"openai_params","frequencyPenalty": 1.5,"presencePenalty": 1.5,"stop": "<|im_end|>","temperature": 0,"topP": 1},"model": "azure__openai__gpt_4o_mini","numTokensForCompletion": 8400,"promptTemplate": "It is, consider these travel options and answer the.","systemMessage": "You are a helpful travel assistant specialized in budget travel"}}}'
132+
$ box ai:extract-structured --items="id=12345,type=file" --metadata-template="type=metadata_template,scope=enterprise,template_key=test" --ai-agent '{"type":"ai_agent_extract_structured","basic_text":{"model":"azure__openai__gpt_4o_mini","prompt_template":"Answer using the provided content"}}'
130133
```
131134

132135
_See code: [src/commands/ai/extract-structured.js](https://github.com/box/boxcli/blob/v4.5.0/src/commands/ai/extract-structured.js)_
@@ -153,8 +156,9 @@ FLAGS
153156
--csv Output formatted CSV
154157
--dialogue-history=<value>... The history of prompts and answers previously passed to the LLM.
155158
--fields=<value> Comma separated list of fields to show
156-
--items=<value>... (required) The items to be processed by the LLM, often files. The array can include
157-
exactly one element.
159+
--items=<value>... (required) Items for text generation. Format: id=FILE_ID,type=file (or
160+
content=TEXT,type=file). Supported keys: id, type, content. Exactly one item is
161+
supported.
158162
--json Output formatted JSON
159163
--no-color Turn off colors for logging
160164
--prompt=<value> (required) The prompt for the AI request

‎docs/authentication.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,15 @@ overview of how the Box API handles authentication.
1919
Ways to Authenticate
2020
--------------------
2121

22+
Use this quick comparison to choose the right method:
23+
24+
| Method | Best for | User interaction | Main setup command |
25+
|--------|----------|------------------|--------------------|
26+
| Developer Token | Quick local testing | Manual token copy/paste | Use `--token` on any command |
27+
| OAuth 2.0 (`box login`) | Interactive user workflows | Yes (browser auth) | `box login -d` (quick start) |
28+
| JWT | Server-to-server automation | No | `box configure:environments:add /path/to/config.json` |
29+
| CCG | Server-to-server automation (no keypair) | No | `box configure:environments:add /path/to/config.json --ccg-auth` |
30+
2231
### Developer Token
2332

2433
A developer token is a token that you can generate directly from the [Box Developer Console][dev-console]. It provides a quick way to test API calls without setting up a full authentication flow.

‎docs/configure.md‎

Lines changed: 51 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Configure the Box CLI
66
* [`box configure:environments:add PATH`](#box-configureenvironmentsadd-path)
77
* [`box configure:environments:delete [NAME]`](#box-configureenvironmentsdelete-name)
88
* [`box configure:environments:get`](#box-configureenvironmentsget)
9+
* [`box configure:environments:list`](#box-configureenvironmentslist)
910
* [`box configure:environments:select [ID]`](#box-configureenvironmentsselect-id)
1011
* [`box configure:environments:set-current [ID]`](#box-configureenvironmentsset-current-id)
1112
* [`box configure:environments:switch-user [USERID]`](#box-configureenvironmentsswitch-user-userid)
@@ -14,15 +15,21 @@ Configure the Box CLI
1415

1516
## `box configure:environments:add PATH`
1617

17-
Add a new Box environment
18+
Add a new Box environment from a Box app config file (JWT or CCG).
1819

1920
```
2021
USAGE
2122
$ box configure:environments:add PATH [--no-color] [-h] [-v] [-q] [--private-key-path <value>] [--set-as-current] [-n <value>]
2223
[--ccg-user <value> --ccg-auth]
2324
2425
ARGUMENTS
25-
PATH Provide a file path to configuration file
26+
PATH
27+
Path to the Box app configuration JSON file.
28+
JWT: download this file from your application in Developer Console:
29+
https://cloud.app.box.com/developers/console
30+
CCG: create this JSON file yourself using values from your application
31+
in Developer Console (Client ID and Client Secret from Configuration tab,
32+
Enterprise ID from General Settings tab).
2633
2734
FLAGS
2835
-h, --help
@@ -38,8 +45,9 @@ FLAGS
3845
Show verbose output, which can be helpful for debugging
3946
4047
--ccg-auth
41-
Add a CCG environment that will use service account. You will have to provide enterprise ID with client id and
42-
secret.
48+
Add a CCG environment that will use a service account.
49+
Open your application in Box Developer Console and create this config JSON yourself.
50+
Required fields: boxAppSettings.clientID, boxAppSettings.clientSecret, enterpriseID.
4351
4452
--ccg-user=<value>
4553
Provide an ID for a user for CCG. Use it to obtain user token. In order to enable generating user token you have to
@@ -57,7 +65,19 @@ FLAGS
5765
Set this new environment as your current environment
5866
5967
DESCRIPTION
60-
Add a new Box environment
68+
Add a new Box environment from a Box app config file (JWT or CCG).
69+
Open your application in Box Developer Console to get/create config data:
70+
https://cloud.app.box.com/developers/console
71+
72+
For OAuth (an alternative to server-side auth), add environment with: box login.
73+
Quick start: box login -d (logs the user in via the Box Official CLI App).
74+
75+
EXAMPLES
76+
$ box configure:environments:add ~/Downloads/my_app_config.json
77+
78+
$ box configure:environments:add ./config.json --name production --set-as-current
79+
80+
$ box configure:environments:add ./config.json --ccg-auth --name ci-bot
6181
```
6282

6383
_See code: [src/commands/configure/environments/add.js](https://github.com/box/boxcli/blob/v4.5.0/src/commands/configure/environments/add.js)_
@@ -103,10 +123,36 @@ FLAGS
103123
104124
DESCRIPTION
105125
Get a Box environment
126+
127+
ALIASES
128+
$ box configure:environments:list
106129
```
107130

108131
_See code: [src/commands/configure/environments/get.js](https://github.com/box/boxcli/blob/v4.5.0/src/commands/configure/environments/get.js)_
109132

133+
## `box configure:environments:list`
134+
135+
Get a Box environment
136+
137+
```
138+
USAGE
139+
$ box configure:environments:list [--no-color] [-h] [-v] [-q] [-c | -n <value>]
140+
141+
FLAGS
142+
-c, --current Get the current default Box environment
143+
-h, --help Show CLI help
144+
-n, --name=<value> Get a Box environment with this name
145+
-q, --quiet Suppress any non-error output to stderr
146+
-v, --verbose Show verbose output, which can be helpful for debugging
147+
--no-color Turn off colors for logging
148+
149+
DESCRIPTION
150+
Get a Box environment
151+
152+
ALIASES
153+
$ box configure:environments:list
154+
```
155+
110156
## `box configure:environments:select [ID]`
111157

112158
Set your current Box environment to use

‎docs/files.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -406,7 +406,7 @@ FLAGS
406406
--fields=<value> Comma separated list of fields to show
407407
--json Output formatted JSON
408408
--no-color Turn off colors for logging
409-
--[no-]overwrite Overwrite a file if it already exists
409+
--[no-]overwrite Overwrite a file if it already exists (prevents overwrite prompt)
410410
--save-as=<value> The filename used when saving the file
411411
--save-to-file-path=<value> Override default file path to save report
412412
--version=<value> File version ID of the specific file version to download
@@ -1526,7 +1526,7 @@ FLAGS
15261526
--fields=<value> Comma separated list of fields to show
15271527
--json Output formatted JSON
15281528
--no-color Turn off colors for logging
1529-
--[no-]overwrite Overwrite a file if it already exists
1529+
--[no-]overwrite Overwrite a file if it already exists (prevents overwrite prompt)
15301530
--save-as=<value> The filename used when saving the file
15311531
--save-to-file-path=<value> Override default file path to save report
15321532

‎docs/login.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Login options:
88
(1) Official Box CLI App
99
No app setup needed. Use --default-box-app (-d) to skip the prompt.
1010

11-
(2) Your own Platform OAuth app
11+
(2) Your own Platform OAuth App
1212
Enter your Client ID and Client Secret when prompted. Use --platform-app to skip the prompt.
1313

1414
Quickstart: run "box login -d" to sign in immediately. A browser window will open for authorization. Once access is granted, the environment is created and set as default — you can start running commands right away.
@@ -70,7 +70,7 @@ DESCRIPTION
7070
(1) Official Box CLI App
7171
No app setup needed. Use --default-box-app (-d) to skip the prompt.
7272
73-
(2) Your own Platform OAuth app
73+
(2) Your own Platform OAuth App
7474
Enter your Client ID and Client Secret when prompted. Use --platform-app to skip the prompt.
7575
7676
Quickstart: run "box login -d" to sign in immediately. A browser window will open for authorization. Once access is

‎docs/metadata-query.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,8 @@ USAGE
1717
[--order-by <value>] [--limit <value>] [--marker <value>] [--extra-fields <value>]
1818
1919
ARGUMENTS
20-
FROM The template used in the query. Must be in the form scope.templateKey
20+
FROM The template used in the query. Must be in the form scope.templateKey (for example
21+
enterprise_12345.contractTemplate)
2122
ANCESTORFOLDERID The folder_id to which to restrain the query
2223
2324
FLAGS
@@ -55,6 +56,8 @@ DESCRIPTION
5556
5657
EXAMPLES
5758
$ box metadata-query enterprise_12345.someTemplate 5555 --query "amount >= :minAmount AND amount <= :maxAmount" --query-params minAmount=100f,maxAmount=200f --use-index amountAsc --order-by amount=ASC --extra-fields created_at,metadata.enterprise_1234.contracts
59+
60+
$ box metadata-query enterprise_12345.contractTemplate 12345 --query "status = :status" --query-param status=active
5861
```
5962

6063
_See code: [src/commands/metadata-query.js](https://github.com/box/boxcli/blob/v4.5.0/src/commands/metadata-query.js)_

‎docs/metadata-templates.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,11 @@ ALIASES
4242
$ box metadata-templates:list
4343
4444
EXAMPLES
45-
$ box metadata-templates
45+
$ box metadata-templates:list
46+
47+
$ box metadata-templates:list --json
48+
49+
$ box metadata-templates:list --fields templateKey,displayName,scope
4650
```
4751

4852
_See code: [src/commands/metadata-templates/index.js](https://github.com/box/boxcli/blob/v4.5.0/src/commands/metadata-templates/index.js)_
@@ -246,7 +250,11 @@ ALIASES
246250
$ box metadata-templates:list
247251
248252
EXAMPLES
249-
$ box metadata-templates
253+
$ box metadata-templates:list
254+
255+
$ box metadata-templates:list --json
256+
257+
$ box metadata-templates:list --fields templateKey,displayName,scope
250258
```
251259

252260
## `box metadata-templates:update TEMPLATEKEY`

‎docs/request.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,13 @@ FLAGS
4040
4141
DESCRIPTION
4242
Manually specify a Box API request
43+
44+
EXAMPLES
45+
$ box request /users/me
46+
47+
$ box request /folders/0/items --query "limit=5"
48+
49+
$ box request /folders -X POST --body '{"name":"New Folder","parent":{"id":"0"}}'
4350
```
4451

4552
_See code: [src/commands/request.js](https://github.com/box/boxcli/blob/v4.5.0/src/commands/request.js)_

‎docs/search.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,9 @@ FLAGS
4949
--include-recent-shared-links Returns shared links that the user recently accessed
5050
--json Output formatted JSON
5151
--limit=<value> Defines the maximum number of items to return. Default value is 100.
52-
--mdfilter=<value>... Metadata value to filter on, in the format <scope>.<templateKey>.<field>=<value>
52+
--mdfilter=<value>... Metadata value to filter on, in the format <scope>.<templateKey>.<field>=<value>.
53+
For enterprise templates, scope is usually enterprise_<enterpriseID> (for example
54+
enterprise_123456).
5355
--no-color Turn off colors for logging
5456
--owner-user-ids=<value> Search for objects by owner. Requires a user ID or a set of comma-delimited user
5557
IDs

‎docs/tokens.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ _See code: [src/commands/tokens/exchange.js](https://github.com/box/boxcli/blob/
3737

3838
## `box tokens:get`
3939

40-
Get a token. Returns the service account token by default
40+
Generate a new access token. Returns a service account token for the default environment unless --user-id is specified.
4141

4242
```
4343
USAGE
@@ -46,12 +46,18 @@ USAGE
4646
FLAGS
4747
-h, --help Show CLI help
4848
-q, --quiet Suppress any non-error output to stderr
49-
-u, --user-id=<value> Get a user token from a user ID
49+
-u, --user-id=<value> Generate a user token for the specified user ID
5050
-v, --verbose Show verbose output, which can be helpful for debugging
5151
--no-color Turn off colors for logging
5252
5353
DESCRIPTION
54-
Get a token. Returns the service account token by default
54+
Generate a new access token. Returns a service account token for the default environment unless --user-id is
55+
specified.
56+
57+
EXAMPLES
58+
$ box tokens:get
59+
60+
$ box tokens:get --user-id 12345
5561
```
5662

5763
_See code: [src/commands/tokens/get.js](https://github.com/box/boxcli/blob/v4.5.0/src/commands/tokens/get.js)_

0 commit comments

Comments
 (0)