Box CLI 2.0 - having trouble, could use some examples

Highlighted
Occasional Contributor

Box CLI 2.0 - having trouble, could use some examples

Hey, folks. I'm trying out the Box CLI tool, and having trouble getting my head around it.  I downloaded and installed it for Windows, followed the getting started blurb, set up my app and approved it for my enterprise.  I can seem to make queries if I paste in the app's dev token, but otherwise I seem to get nothing but 403s.

 

The feature I'm most excited about is the possibility of feeding the CLI tool a CSV to automate processing a list of items, but I can't see anything in the docs about what that CSV should include or how it should be arranged.

 

Has anyone here worked with the new version enough to understand how it handles permissions or bulk ops? I think a few examples would go a long way.  Thanks in advance.

15 REPLIES 15
Highlighted
Box Employee

Re: Box CLI 2.0 - having trouble, could use some examples

Hi @GQRRAdmin — I'm Matt, one of the engineers on the Box SDK team.  I helped build the CLI v2, and I think I can help you out a bit here!  If I had to guess, I'd say the 403 issue you're seeing might be due to a detail of how your application and CLI are set up: by default, the CLI is authenticated as a Service Account, not your own account.  That account has its own file and folders, and in general doesn't have the same access that your Box account does.  If you're trying to run commands as your own user, you should be able to do that like this:

 

  1. Make sure that under "Application Access" in the Configuration tab for your app in the Box Developer Console, you've selected "Enterprise"
  2. In the same Configuration tab, make sure that under "Advanced Features" you've selected "Perform Actions as Users"
  3. Set the CLI to run commands as your account instead of the Service Account by running box configure:environments:switch-user [YOUR OWN USER ID]

As for the bulk input, it's actually super easy to determine what to put in the CSV for any command — it's the same as what you see when you run the command with --help and you should be able to use any of the argument or flag names as CSV column headers.  The order shouldn't matter at all.

 

If you have any other questions, problems, or feature requests for the CLI, the best place to contact us is by filing an Issue directly on the CLI GitHub repo; our team monitors that closely and would be more than happy to assist you!

Highlighted
Occasional Contributor

Re: Box CLI 2.0 - having trouble, could use some examples

Thanks, I'll give that a try. If it works, I'll try adding it to the Getting Started blurb and make a pull request, because as-is, that blurb is not enough to actually get started with anything.

Highlighted
Occasional Contributor

Re: Box CLI 2.0 - having trouble, could use some examples


@mwiller wrote:

Hi @GQRRAdmin — I'm Matt, one of the engineers on the Box SDK team.  I helped build the CLI v2, and I think I can help you out a bit here!  If I had to guess, I'd say the 403 issue you're seeing might be due to a detail of how your application and CLI are set up: by default, the CLI is authenticated as a Service Account, not your own account.  That account has its own file and folders, and in general doesn't have the same access that your Box account does.  If you're trying to run commands as your own user, you should be able to do that like this:

 

  1. Make sure that under "Application Access" in the Configuration tab for your app in the Box Developer Console, you've selected "Enterprise"
  2. In the same Configuration tab, make sure that under "Advanced Features" you've selected "Perform Actions as Users"
  3. Set the CLI to run commands as your account instead of the Service Account by running box configure:environments:switch-user [YOUR OWN USER ID]

As for the bulk input, it's actually super easy to determine what to put in the CSV for any command — it's the same as what you see when you run the command with --help and you should be able to use any of the argument or flag names as CSV column headers.  The order shouldn't matter at all.

 

If you have any other questions, problems, or feature requests for the CLI, the best place to contact us is by filing an Issue directly on the CLI GitHub repo; our team monitors that closely and would be more than happy to assist you!


Well, I followed those steps quite carefully, and still no joy.  It's still 403s as far as the eye can see, with the odd exception of generating tokens, apparently.  I also took the (undocumented) step of opening a support case to get the 'global content manager' scope enabled for my app's client ID.  Redacted transcript follows:

 

Windows PowerShell
Copyright (C) 2016 Microsoft Corporation. All rights reserved.

> box users:get me
Type: user
ID: '123456789'
Name: AutoDiscovery
Login: ***email address removed for privacy***
Created At: '2019-02-06T12:50:25-08:00'
Modified At: '2019-02-06T12:50:47-08:00'
Language: en
Timezone: America/New_York
Space Amount***phone number removed for privacy***Space Used: 0
Max Upload Size: ***phone number removed for privacy***Status: active
Job Title: ''
Phone: ''
Address: ''
Avatar URL: 'https://gqrr.app.box.com/api/avatar/large/123456789'

> box configure:environments:switch-user 9999999
User set to 9999999

> box users:get me
Unexpected API Response [403 Forbidden]

> box users:get
Unexpected API Response [403 Forbidden]

> box configure:environments:delete default
The default environment was deleted

> box users:get
No default environment found.
It looks like you haven't configured the Box CLI yet.
See this command for help adding an environment: box configure:environments:add --help
Or, supply a token with your command with --token.

> box configure:environments:add .\.box\12345_abcdefgh_config.json
Successfully added CLI environment "default"

> box users:get
Type: user
ID: '123456789'
Name: AutoDiscovery
Login: ***email address removed for privacy***
Created At: '2019-02-06T12:50:25-08:00'
Modified At: '2019-02-06T12:50:47-08:00'
Language: en
Timezone: America/New_York
Space Amount***phone number removed for privacy***Space Used: 0
Max Upload Size: ***phone number removed for privacy***Status: active
Job Title: ''
Phone: ''
Address: ''
Avatar URL: 'https://gqrr.app.box.com/api/avatar/large/123456789'

> box users:get 9999999
Type: user
ID: '9999999'
Name: Administrator
Login: [redacted]
Created At: '2010-05-21T14:25:38-07:00'
Modified At: '2019-03-20T08:46:18-07:00'
Language: en
Timezone: America/New_York
Space Amount: 999999995044170
Space Used: 590***phone number removed for privacy***Max Upload Size: ***phone number removed for privacy***Status: active
Job Title: ''
Phone: '1234567890'
Address: ''
Avatar URL: 'https://gqrr.app.box.com/api/avatar/large/9999999'

> box configure:environments:switch-user 9999999
User set to 9999999

> box users:get 9999999
Unexpected API Response [403 Forbidden]

> box users:get
Unexpected API Response [403 Forbidden]

> box groups
Unexpected API Response [403 Forbidden]

> box search Alaska
Unexpected API Response [403 Forbidden]

> box search "Alaska"
Unexpected API Response [403 Forbidden]

> box trash
Unexpected API Response [403 Forbidden]

> box tokens:get
7G5EJYrlE40q4wmX4b6bgYC4tSi4dd7J

> box trash
Unexpected API Response [403 Forbidden]

> box users
Unexpected API Response [403 Forbidden]

Replying here instead of on GitHub so that this thread will be visible to other Box CLI would-be users who might run into the same problems.  If you'd like, I'll open a parallel Issue on GitHub, but squirreling this away seems undesireable.

 

To explain my use-case: we just want to be able to do administration at the command-line. This isn't for some app.  This is so our Box admins can save a few thousand clicks, script and QC large permissions changes before we make them, maybe put those permissions changes under version control.  Only our administrators will ever use the CLI.  If they need to log into it, that's fine, although it's not clear to me how to do that (especially since we federate our logins through Okta).  Our Box users will never touch it, and there are no Platform/App users.

 

Any further advice would be appreciated.

 

Highlighted
Occasional Contributor

Re: Box CLI 2.0 - having trouble, could use some examples

Trying to do the same as OP. 404s with app user, when I switched users to my global admin I got 403 errors

Highlighted
Occasional Contributor

Re: Box CLI 2.0 - having trouble, could use some examples

After running `box users:get` and sharing to the app user email (...@boxdevedition.com) to a folder I was able to do a folders:get on that specific folder. How do I give the app user account the permission to access everything? Even if I switch to the account that is the owner of a folder I'm getting 403 errors. How can you do anything if you need to switch to the user owner of a file/folder and then that user just gets 403s for their own content? It's really frustrating trying to use this tool

Highlighted
Occasional Contributor

Re: Box CLI 2.0 - having trouble, could use some examples


@dcoleHCG wrote:

After running `box users:get` and sharing to the app user email (...@boxdevedition.com) to a folder I was able to do a folders:get on that specific folder. How do I give the app user account the permission to access everything? Even if I switch to the account that is the owner of a folder I'm getting 403 errors. How can you do anything if you need to switch to the user owner of a file/folder and then that user just gets 403s for their own content? It's really frustrating trying to use this tool


Wow, am I glad to hear you say that.  I was starting to think I was crazy.  Glad to hear I'm not the only one.

 

I've checked the scopes, re-authorized the app in my Enterprise (I'm an enterprise admin), re-genned keypairs half a dozen times, and none of it has worked.

 

Is it possible this CLI just doesn't work on Enterprise data and Managed Users? It sort of looks like it's intended to be used by Box Platform devs, which confused me because I don't know why they wouldn't use direct APIs or SDKs. It's Enterprise admins that would benefit most from a CLI.  Am I misreading something one way or another?

Highlighted
Occasional Contributor

Re: Box CLI 2.0 - having trouble, could use some examples

Well, I seem to have stumbled onto something.  I was getting 403s on anything after doing the configure:environments:switch-user command, until I happened to try adding the (what I thought would be redundant) --as-user flag to something.  Then it suddenly worked, and worked subsequently also with or without the flag.  I'm really not sure what's going on there, but it's working. Yay?

 

Hope that maybe helps someone else. Also maybe you can corroborate this behavior?

 

Highlighted
Occasional Contributor

Re: Box CLI 2.0 - having trouble, could use some examples

I actually was able to get this all to work after getting the Global Content rights (which should be stated somewhere, rather than spending an hour pulling hair out then submitting a ticket). Support added those rights and I reauthorized the app, now not having any issues. My config is

 

OAuth 2.0 w/ JWT

Enterprise Application Access

Global Content Manager scope (need to request via Box ticket)

Advanced Features - Perform Actions as Users

Generated key via Box

 

don't need to run commands as-user, just using the app service account that defaults when you configure your environment with the pub key .json

Highlighted
First-time Contributor

Re: Box CLI 2.0 - having trouble, could use some examples

Just wanted to see if this is really the only solution. Can anyone from box.com weigh in here?

Highlighted
New Contributor

Re: Box CLI 2.0 - having trouble, could use some examples

I'm having a hard time with this as well.

 

I have followed the published docs and granted:
Appl access: Enterprise
Appl scope: [x] Read and Write all files and folders stored in box

 

But when I try to list folder items of another user
C:\> box folders:items 999 <where 999 is a valid folder#>
Unexpected API Response [404 Not Found | 3b41regg41sfasjg.0f9886a222fe153de11dbab9fb6d4fe85] not_found - Not Found

 

What are these comments about needing to request MORE rights to the service account via support ticket?
The docs on creating these accounts say nothing about that.

What is the point of the Enterprise check box, and the "read write ALL users" check box, if they don't actually grant that?!

 

Email back and forth with support on this and other questions, not any help.

@mwillercan you help here?

 

Highlighted
New Contributor

Re: Box CLI 2.0 - having trouble, could use some examples

I'm having the same issue.

Box Employee

Re: Box CLI 2.0 - having trouble, could use some examples

Hi there @GQRRAdmin @devin-p @dcoleHCG @Flagstone @jflournoy 

 

It sounds like there are a few different problems going on here, so I'll try to clarify a few of the behaviors of Box and the CLI that may not be obvious:

 

1. In Box, the default behavior is that a user (and I mean any user, including an enterprise administrator or service account) can not arbitrarily access a file or a folder to which the user lacks "collaborator" access. For example, consider a regular managed user (called "m_user" for this discussion) that creates a new folder with id 123 in his root (folder 0). We'll refer to the logical "path" to this folder is m_user\0\123. If you create a CLI environment using a Service Account, then when you try to use box:folders:get 123 it will throw a 404 error. This is because the Service Account (which is just another type of user) is not a collaborator on folder 123. If, however, m_user invites the service account to that folder, the command will return succesfully.

 

2. The As-User capabilility enables applications with the scope "Perform Actions as User" to impersonate another user when making API calls. This provides a means to access content that (1) would otherwise prevent. If you are using a Service Account, which is created when you select OAuth 2.0 with JWT (Service Authentication), then the default Application Access is set as "Application."  This will only allow you to use the As-User capability on app users that you create. If you instead select "Enterprise" for Application Access, you can use As-User on managed users as well. Going back to the example in (1) - we can add the As-User capability to do a direct lookup on the folder at m_user\0\123 by sending the command with the as-user flag with the id of m_user ->  box:folders get 123 --as-user=userIdOfm_user

 

3. You cannot "As-User" yourself - doing so will result in a 403 error. I suspect this is where most people are getting tripped up with 403s. Unfortunately it would appear that if you try to switch user context in the CLI and then switch the user-id back to your service account, commands will attempt to send the As-User header with your own user id, which results in a 403. I can't find a way to null out the defaultAsUserId value, so the only way I found to resolve this was to delete and recreate the environment. See below for an example of this behavior in which I specify the user-id as the Service Account and then start getting 403s. 

 

C:\Users\ddennhardt>box users:get:me
{
    "type": "user",
    "id": "13126631879",
    "name": "CLI_FORUM_TEST",
    "login": "AutomationUser...@boxdevedition.com",
}

C:\Users\ddennhardt>box configure:environments:get
{
    "CLI": {
        "clientId": "myClientId",
        "enterpriseId": "myEID",
        "boxConfigFilePath": "pathToMyFile",
        "hasInLinePrivateKey": true,
        "privateKeyPath": null,
        "name": "CLI",
        "defaultAsUserId": null,
        "useDefaultAsUser": false,
        "cacheTokens": true
    }
}

C:\Users\ddennhardt>box configure:environments:switch-user 11949667603
User set to 11949667603

C:\Users\ddennhardt>box users:get me
Unexpected API Response [403 Forbidden | q3rzgfgg627ziyqn.07df955300130548ec0a31381f404db89] access_denied_insufficient_permissions - Access denied - insufficient permission

C:\Users\ddennhardt>box configure:environments:delete CLI
The CLI environment was deleted

C:\Users\ddennhardt>box configure:environments:add "pathToMyFile" --name=CLI
Successfully added CLI environment "CLI"

C:\Users\ddennhardt>box users:get me
{
    "type": "user",
    "id": "13126631879",
    "name": "CLI_FORUM_TEST",
    "login": "AutomationUser_1310471_fitXAt5uj0@boxdevedition.com",
}

 

 4. The Global Content Manager scope sort-of provides a bypass to the constraint in (1) but I don't recommend it for a number of reasons; it is primarily to serve the purpose of eDiscovery where an account needs to search/view across all content in an enterprise for litigation and actually predates the As-User capability. If you have the luxury of being able to determine the id values of users that own or have access to the content you're trying to operate on, the As-User capability is superior in almost all cases.

 

Hopefully this helps! Let me know if you're still stuck

Tags (2)
Highlighted
New Contributor

Re: Box CLI 2.0 - having trouble, could use some examples

@dandennhardt 

Thank you for the detailed response. I went through this to make sure I wasnt calling as the as-user set to myself - or the app. 

When I make the following call with any user (regular/coadmin)

box folders:get 123 --as-user=456 -v

I am still getting a 403 Forbidden, even with the application access set to Enterprise.  

 

Anything else I should check?

Highlighted
First-time Contributor

Re: Box CLI 2.0 - having trouble, could use some examples

Hi, 

I've searched high and low for this as well and think I've finally found it. 

Ran:

- box users

- copy the login name

- go to folder on box drive and share by inviting the "login" name copied

 

This seems to grant permissions to my app which now allows me to run the commands successfully.

 

Highlighted
Box Employee

Re: Box CLI 2.0 - having trouble, could use some examples

Just posting for posterity in this thread - @devin-p and I discussed and now believe that the last issue (before resolution) was caused by having not reauthorized the application after adding the "Perform Actions as Users" setting to the application. This setting is necessary to perform the As-User calls, and when app permissions or settings are changed that impact the authorization of the app in an enterprise, the enterprise admin needs to reauthorize the app for those settings to take effect.